Почему на специальности, связанных с программированием не обучают разрабатывать документацию?

Не надо документацию на русском писать.

вот если бы губы Никанора Иваныча тесты писать в стиле BDD. да прикрутить обработку естественных языков, да ещё русского, (например, на базе вот этого — про многоязычные семантические вики и представление знаний). да ещё писать это всё в org-mode babel с single source генерацией того, что соприкасается, то...

1. сабж
2. ???
3. PROFIT!

За одно это выражение «Руководство сис. программиста» я бы уже руки оторвала тому неграмотному идиоту, кто его придумал. Потому что системный программист читает только доки на ось и мануалы на чипы и всё, пожалуй.

Под термином «системный программист» в понимании ЕСПД в те времена имелся в виду сисадмин, просто слова такого тогда не было. Параллельно, конечно, были и настоящие системные программисты, но этот документ не для них.

В ГОСТ 34 уже появилось «Руководство администратора», но это уже не совсем ПД, точнее, совсем не ПД :)

документацию вообще было бы неплохо писать в стиле Interactive Fiction. запускаешь такую roguelike-бродилку, задаёшь вопросы (или что-то делаешь, в GUI щёлкаешь, а оно с бродилкой в фоне текстом разговаривает, и само по ситуации находит, например, вопросы задаёт)

IF уже давно научились совместно через веб разрабатывать. пример и документация к нему в виде IF (нажми там «View game source» и проникнись идеей).

набросать подобное довольно просто, на каком-нибудь Inform7 в духе контролируемых естественных языков

только вот жаль, что русский пока не прикрутили :(((
вообще Inform7 умеет в юникод, но вот с падежами/склонениями/спряжениями туговато...

Это почему?

nekulturna

По тому же, почему и комментарии на русском — моветон.

может, ещё и ключевые слова в языке программирования на русском — это табу?

почему так? ведь англоговорящие native speakers программируют на своём естественном языке!

компьютеру всё равно, хоть иероглифами напиши, или ятями с ерами и словоериками-съ. он железный, ему уже всё равно.

(некоторые считают, что люди и думают на том языке, на котором говорят. я так не думаю — билингвы или визуалы с пространственным мышлением явно в эту схему не вписываются. скорее, они думают на каком-то метаязыке, который переводится почти автоматически в нативный неосознанно, машинально — или более осознанно если человек билингва, например)

hobbit

Да, это вполне себе «табу». Как минимум по той причине, что техническая терминология в русском языке гораздо менее устоявшаяся, чем в английском, и рандомный чтец кода с большой вероятностью будет чесать репу на каждой второй строчке. Смысловые оттенки, обороты речи и так далее — всё это имеет значение.

Исходный код уж стопудово обязан быть только в ASCII. Смотрю на свои старые исходники на сосфорже, и бью себя по рукам за "крякозябры" (т.к. у сосфоржа хрюникод, а у меня — КОИ8).

А еще — любой человек с легкостью прочтет документацию на английском (т.к. английский — международный язык). А вот документацию на русском сможет прочитать от силы с полсотни-сотня миллионов человек...

ок, надмозговые трудности перевода вполне себе причина. или если команда многоязычная. или там разная ширина буков в пикселях и поехавшие интерфейсы при недостаточно продвинутой локализации.

но вот если типичный быдлокодер пишет себе говнокод на другом наречии и думает, что он типа круто выглядит, а на одном наречии автоматически менее круто (безотносительно того что и как этот код делает) — вот это странно весьма.

может, если бы этот мифический быдлокодер вместо брендинга и нейминга изъяснялся бы по-человечески, хотя бы набросав себе понятный псевдокод на нативном наречии — он не боролся бы с ветряными мельницами, а уже двигался бы дальше, решив задачу? не говоря уже об лучшем понимании того, чего он собственно хочет сделать.

а то одни чешут репу, пока код читают, а другие — пока пишут как-нибудь позаковыристей. Dreck in, Dreck out.

а в чём проблема писать README.en.txt и КУИЩЩЕ.ru.txt ?

в общем, такое ощущение, что мы, программисты сами себе придумываем сложности, с которыми героически боремся.

Никто не говорит, что не нужно перед реализацией излагать алгоритм в псевдокоде или как-либо ещё.

Но вот я, например, даже когда прогаю «для себя», выбираю названия и пишу комментарии так же, как если бы коммитил в проект уровня ядра Linux. Просто ради тренировки.

Да я про комментарии в коде (в doxygen-style). А README я частенько просто на двух языках пишу.

мы, программисты сами себе придумываем сложности, с которыми героически боремся

Это вы, программисты. А я — черт-те что и сбоку бантик.

а ты вообще DYI электронщик. респект и уважуха.

* DIY

РЭ - это «Руководство по эксплуатации». Для сложного изделия может состоять из сотен томов.

Руководства по эксплуатации нормальные программисты не пишут. Это не их работа, для этого есть другие люди.

а может, вместо сотен томов надо написать такое (=> «view source»)?

и себе пускай юзеры тыкают? может даже, через 3D GUI MMO интерфейс.

а с человекопонятным контролируемым ЕЯ даже техписы смогут справиться.

По тому же, почему и комментарии на русском — моветон.

Ну с комментариями - допустим, согласен. Хотя и здесь есть разные ситуации...

А документация-то с какого перепугу должна быть на чужом для пользователя языке, если, например, программа пишется изначально для русских заказчиков?

рандомный чтец кода с большой вероятностью будет чесать репу на каждой второй строчке

кода

Мы вроде как про документацию...

Не имеет значения.

если, например, программа пишется изначально для русских заказчиков?

Может еще и русский язык в операторы внедрить, как в ēкселе-мокселе или (пардонте мой французский) 1С?

При чём здесь операторы???

Вот представьте себе, программа пишется для некоей сугубо отечественной фирмы. И вот мы им торжественно приносим руководство оператора (не того оператора, который в языке, а того, который за компом сидит) на английском языке?

финиш элефант из зе бест френд оф рашн элефант! ви аре зэ мазер раша, зе фазерленд оф зе элефантс! аур элефантс аре зе хейриест ванс, энд ви колл зем маммотс! маммотс оф зе ворлд, юнайтс!

Ты меня бухгалтерскими программами не пугай! Я их и так боюсь!

Лично мне нафиг не нужен мануал на русском — я только запутаюсь в корявом и устаревшем переводе!!! Ну, если он оригинальный будет — еще ладно, если продукт не ориентирован на весь мир.

Но я с софтом, ориентированным сугубо на российского производителя не сталкивался. И не собираюсь с этой бухгалтерской дрянью сталкиваться.

Йес! Аур трэйнс из зе мост трэйнест трэйнс ин зэ ворлд! Энд зерез ноу озер трэйн зэт вилл овертрэйн аур трэйнс!

// кошмар! Пока это писал — замучился! Руки так и норовили нормально писать...

Но я с софтом, ориентированным сугубо на российского производителя не сталкивался. И не собираюсь с этой бухгалтерской дрянью сталкиваться.

Ээээ....

То есть о существовании НЕбухгалтерского софта, выпускаемого для российского потребителя ты даже не слышал?

То есть о существовании НЕбухгалтерского софта, выпускаемого для российского потребителя ты даже не слышал?

Я с ним никогда не сталкивался. И даже не представляю, что это за софт может быть. Разве что хитрожопый интерфейс пуска ядерных бомб?

По тому же, почему и комментарии на русском — моветон.

это точно. комментарии лучше на английском писать. работала в командах разработчиков совместно с иностранцами, и на работе, и в опенсорце. с тех пор никаких кириллических кракозябр в коде. даже строки, если требуется русский интерфейс, выношу через i18n (gettext) в отдельные файлы, из которых потом легко и просто генерится интерфейс на любом языке. а ещё есть извращенцы, которые называют переменные как-то типа peremennaya. и тогда программа превращается вообще в полный мрак.

А если продукт - библиотека? Кому, как не разработчикам, документировать ее?

Разве что хитрожопый интерфейс пуска ядерных бомб?

Ну и это тоже, оборонка, космос - ёмкие рынки.

Но не только они. Как насчёт программ для школ, например?

Кстати говоря, ТС довольно чётко очертила область дискуссии: «заказное ПО». То есть ПО, которое делается по заказу конкретной фирмы или учреждения, и документация на него, как правило, должна быть на вполне определённом языке - на том, который нужен заказчику.

Другое дело, что похоже, не менее чем половине участников дисскуссии в этой теме термин «заказное ПО» ничего не говорит...

космос

Там нафиг не нужен русский язык, потому что обычно все делается международным!

программ для школ

В школах информатика только вредна! А в таком виде, как сейчас, скоро и школьное "образование" вообще будет вредно!

Там нафиг не нужен русский язык, потому что обычно все делается международным!

Ну-ну )))

В школах информатика только вредна!

Тебе не приходит в голову, что обучающие программы бывают не только и даже не столько по информатике?

А если продукт - библиотека? Кому, как не разработчикам, документировать ее?

В таком случае, конечно, разработчикам.

Но РЭ документ немного другого рода, и для библиотеки он вроде как и вообще не нужен.

Ты не осилил нормально прочитать сообщение

И что же от меня ускользнуло? По-моему, там было ровно три тезиса. На третий я даже отвечать не стал - больно уж на 4.1 смахивает...

Если совсем не будет - не продашь - никто ж не поймет как им пользоваться. Проблема на мой взгляд как раз в неполной документации и завышенном количестве «чёрных ящиков». Идея то хороша - но когда даже в самой конторе-разработчике ПО не могут сказать как же эта хрень работает и почему не работает так как надо - это печально.

ещё есть извращенцы, которые называют переменные как-то типа peremennaya. и тогда программа превращается вообще в полный мрак.

А извращенцы, которые поле ИНН в программе называют ITN, а код по ОКОФ — ACFA (all-russian classifier of fixed assets) лучше?

с тех пор никаких кириллических кракозябр в коде

А если это программа для расчёта налога на прибыль? Будешь цитаты из налогового кодекса (на основании которых строишь алгоритм) на английский переводить?

лучше?[/quite] лучше. потому что если разработчики из разных стран, то фиг ты им пояснишь, что это за ОКОФ такой. но если это местечковая поделка на коленке - то пофиг. там и на качество кода пофиг, по большому счёту.

Будешь цитаты из налогового кодекса (на основании которых строишь алгоритм) на английский переводить?

не обязательно переводить. тем более, что цитаты никто в код не встраивает (ну, кроме мелкософта, но это оффтоп). есть методы для работы с текстом. и никто никогда в код текст не вставляет. потому что это маразм.

тем более, что цитаты никто в код не встраивает

Не в код, в комментарий. Имеется в виду комментарий вида

/* ст 214.2 НК РФ

...налоговая база определяется как превышение суммы процентов, начисленной в соответствии с условиями договора, над суммой процентов, рассчитанной по рублевым вкладам исходя из ставки рефинансирования Центрального банка Российской Федерации, увеличенной на пять процентных пунктов, действующей в течение периода, за который начислены указанные проценты..
*/
TaxBase = (Rate- RateCBR - 5) * DepositAmount;

Если переводить, то может получиться ошибка при переводе, а не при реализации. Если оставлять только ссылку на кодекс, то ещё хуже — программисту надо будет найти в кодексе тут статью и также перевести с русского. Как рекомендуешь?

Как рекомендуешь?

линки на документ. русские комментарии - бомба, которая в один прекрасный момент сработает. кто-то откроет текст в системе, где нет русской раскладки и сохранит его. и все ваши комментарии превратятся в тыкву.

но вообще, для таких простых вычислений комментарии особо и не нужны. обычно комментарии пишут к сложным местам в алгоритмах или в каких-то особо запутанных манипуляциях с данными. излишек комментариев в коде тоже мешает пониманию самого кода.

для таких простых вычислений комментарии особо и не нужны

Нужны, если на основании нормативного документа. Как пример, в указанной мной цитате код слегка противоречит комментарию: надо учитывать возможность изменения ставки рефинансирования в период начисления.

Как вариант, на основании нормативных документов пишется спецификация, а в комментариях уже ссылки на пункты спецификации (тогда и спецификацию можно по-английски). Но это подходит только в случае, когда кто-то согласен на себя ответственность за соответствие спецификации и нормативного документа. Часто нормативный документ является спецификацией. А в нём, в свою очередь, бывают неоднозначно трактуемые фразы.

кто-то откроет текст в системе, где нет русской раскладки и сохранит его. и все ваши комментарии превратятся в тыкву

Юникоду уже двадцать лет, как придуман. Сохранять надо в UTF8. Если в шрифте нет нужных символов, то они всё равно сохранятся без изменений. Для Java вообще в другой кодировке не сохранишь — юникод в стандарте.

Вброшу тут: на специальностях, связанных с программированием не обучают разрабатывать программное обеспечение. Учат программировать программы на языках программирования, в лучшем случае.

в указанной мной цитате код слегка противоречит комментарию: надо учитывать возможность изменения ставки рефинансирования в период начисления.

вообще, код должен соответствовать комментариям. иначе смысл комментариев?
учитывать возможность изменения нужно в конфигах. выносить всё в настройки. ну, максимум в макросы в каком-то общем заголовочнике. это если по уму. однако, я понимаю, что наше законодательство совершенно безумно и противоречит любому здравому смыслу, поэтому запрограммировать всё раз и навсегда нереально, особенно с учётом всех внезапных прыжков и ужимок правительства. так что наша рашиянская бухгалтерия, увы, в отличие от R3 (и прочих R-ов) навсегда обречена на говнокод и это не вина программистов. именно поэтому я не занимаюсь подобными вещами: это вечная переделка одного и того же кода, нудная и однообразная. ну и общение с контингентом бюстгалтерий...

когда-то давно, когда я только окончила универ, я как раз писала бухгалтерию для ЖД. объёмы большие, капстроительство, проекты, растянутые на десятилетия, соответственно, все перерасчёты всех деноминаций рубля, покупка и списание большого количества разных материалов по разным ценам и прочее, и прочее - всё это учитывалось. плюс все постоянные изменения закона. так что я знаю, о чём идёт речь. в итоге, самым оптимальным решением оказалось модульное решение: все библиотеки (включая сами формы) грузились в базу, а клиент только вытаскивал из базы библиотеки и загружал их. таким образом, всё было разделено на кучу мелких и независимых кусков, каждый из которых переписать было легко и загрузка в базу меняла софт сразу у всех клиентов, без необходимости апдейтов. сама структура софтины также тащилась из базы, поэтому добавление любых документов также было делом правки таблицы и загрузки пары новых библиотек. вот такой чисто программистский подход к маразму, который творится в бухгалтерии. это существенно уменьшило гемор для разработчиков и повысило скорость выпуска разных патчей для очередных изменений в налогах и т.д. мы даже завоевали медаль на ВДНХ.

но я вообще писала не про нашу унылую реальность, а про нормальную разработку, без внезапных изменений ТЗ каждую неделю.

согласен. тащем-то, топикстартер озвучила нормальный вопрос: «почему инженеры-конструктора могут разработать полный комплект КД, а инженеры-программисты — не могут в полный комплект ПД»?

1. средний инженеры-конструктор тоже не умеет выдать полный комплект КД. это умеет ведущий.
2. умение выдавать работающий код, и выдавать полезную, работающую документацию — это разные. и требовать всего с людей, которые не умеют писать документацию читаемую, а не мертворожденную (так же как умение писать код, а не спеки на код) — это как минимум странно. хороший начальник адекватно распределяет работы тем, у кого какая работа получится лучше.
3. не все программисты — инженеры-программисты. некоторые умеют только кодировать, но не умеют в документацию.
4. полезная, работающая документация — обычно более легковесная, чем по ГОСТ 39.*.

Я кто-нить знает опенсурсный проект, с нормальной документацией (UML или ещё что)?