Комментирование и вообще документация продукта

Н-12>> странно, вроде немало тех, кто не нуждаясь в оплате своего труда вполне себе созидательно трудится.
Zenitchik> В основном - это умственный труд. Кроме того, относительно населения, таких энтузиастов, вероятно, исчезающе мало. Я сам, будучи программистом, очень люблю свою работу. Но если бы не потребность в зарплате - работал бы гораздо меньше.
А главное - совсем не так и не над тем.

Например, всем программистам, развивающим продукт, хочется иметь хорошую документацию по сложному продукту (подробное описание АПИ, примеры, подводных камней). Но мало кому нравится документацию писать.
Сидеть на саппорте, копаться в пользовательских "а вот тут я так, а вот там оно вдруг!" и фиксить баги - тоже мало кому интересно. Почти 100% людей, кто работает из интереса, предпочёл бы реализовывать новую фичу, рефакторить код, что-то улучшать.

Если убрать чисто материальный стимул даже из такой творческой профессии как программирование, отрасль перестанет существовать.
И пример Линукса это подчёркивает: сейчас большинство нудной, но нужно работы делается программистами на зарплате, чей труд "вносит" в общую копилку вполне себе капиталистическая контора, зарабатывающая на чём-то другом. Зато вот от свобод творчества мы получили множество несовместимых систем, подсистем и даже целых дистрибутивов.

Татарин> Например, всем программистам, развивающим продукт, хочется иметь хорошую документацию по сложному продукту (подробное описание АПИ, примеры, подводных камней). Но мало кому нравится документацию писать.

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

Татарин> рефакторить код, что-то улучшать.

Во-от! Документацию, например. Вернее, комментарии, из которых она собирается.

Zenitchik> Вот только в данном конкретном вопроса, работодатель не стимулирует этого делать, и программисту приходится как-то крутиться, и урывать время у задач, чтобы написать эту чёртову документацию. Потому что иначе - всё развалится.
Когда не выделяют времени, и документация - плод личной инициативы ("иначе всё развалится"), тогда документации мало, но зато она по делу.
Когда выделяют специальный таск и (особенно!) специального человека, всё становится хуже, потому что часто она генерируется каким-нить доксигеном, пишется на "отвалите уже", а то и вовсе - исходит от человека, который код в лучшем случае быстро глазами пробежал. И получившееся г**но никто не читает, на него просто молятся - "у нас есть документация". Больше доков богу доков.

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

Татарин>> рефакторить код, что-то улучшать.
Zenitchik> Во-от! Документацию, например. Вернее, комментарии, из которых она собирается.
Не.
Мало такого видел, чтобы вот сидит чел, ему скучно, думает - а ну-ка я доки, которых никто не требовал, попишу. Комментарии пишутся обычно непосредственно в процессе работы с кодом - оставить себе или другому заметку о неочевидностях.
Когда их начинают писать специально, очень часто получается в духе первокурсников a=b;//присваиваем а значение б - раздуто и бессмысленно.

Я вообще придерживаюсь мысли, что чем меньше комментариев внутри кода - тем лучше, потому что комментировать нужно только неочевидное, и если у тебя код имеет наименования, интерфейсы, логику работы такую, что без поллитра не разобрать, то у тебя проблемы с кодом.
Да, часто реально без комментариев не обойтись. Но нужно помнить, что почти всегда это из-за твоей тупости - ты не смог сделать сам код красивее, понятнее и логичнее. К описаниям интерфейсов/вызовов/форматов данных/структур/классов это не относится, ессно.

Татарин> а ну-ка я доки, которых никто не требовал, попишу.

Ну да. Увидел функцию, взял, да и оформил ей стандартный коммент:
/**

• @function sin
• @param a : Number - аргумент синуса
• @return {Number} - синус переданного аргумента

*/

Татарин> Я вообще придерживаюсь мысли, что чем меньше комментариев внутри кода - тем лучше, потому что комментировать нужно только неочевидное

Это слишком генеральная идея. Логика не должна быть такой чёрно-белой.
Нужен стандарт, как пишутся доки. Я, например, придерживаюсь слегка изменённого JSDoc.

Татарин> К описаниям интерфейсов/вызовов/форматов данных/структур/классов это не относится, ессно.

Вы боретесь с ветряными мельницами. Я говорю "комментарии", а имею в виду "описание API, данное в комментариях".
Кроме этого, в комментариях может находиться название применённого алгоритма, или его краткое описание, если он сильно нестандартный. Может какое-то уравнение, которое присутствует в коде в неявном виде, но чтобы было нагляднее - полезно записать в виде условия.

x = (рассчитываю через y);
/* y === a*x**2 + b*x + c */

Zenitchik> Ну да. Увидел функцию, взял, да и оформил ей стандартный коммент:
А толку? Мне вот надо нарисовать круг, каким местом я должен догадаться что для этого нужно именно эту функцию использовать?
"Ответ ваш был столь же точен, сколь и бесполезен!" (ц) анекдот

Дем> А толку?

Толк подобных комментариев трудно переоценить.

Дем> Мне вот надо нарисовать круг, каким местом я должен догадаться что для этого нужно именно эту функцию использовать?

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

Дем> "Ответ ваш был столь же точен, сколь и бесполезен!" (ц) анекдот
Вы, очевидно, не программист.

Дем>> "Ответ ваш был столь же точен, сколь и бесполезен!" (ц) анекдот
Zenitchik> Вы, очевидно, не программист.

Ну я программист.
И тоже слабого мнения относительно комментариев под каждым чихом.
Документировать имеет смысл диаграмму классов, инстанцирования и последовательности, а на это, как правило, нет времени - далее скетча/концепта дело обычно не идет, да и его хватает.
Назначение и логика простых методов видна прямо из кода.
А архитектура - повод для перманентных срачей, потому что каждый знает как лучше

Дем>>> "Ответ ваш был столь же точен, сколь и бесполезен!" (ц) анекдот
Zenitchik>> Вы, очевидно, не программист.
yacc> Ну я программист.
yacc> И тоже слабого мнения относительно комментариев под каждым чихом.
yacc> Документировать имеет смысл диаграмму классов, инстанцирования и последовательности, а на это, как правило, нет времени - далее скетча/концепта дело обычно не идет, да и его хватает.
yacc> Назначение и логика простых методов видна прямо из кода.
yacc> А архитектура - повод для перманентных срачей, потому что каждый знает как лучше

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

с.т.> если подразумевается переиспользование и передача 3им лицам то без документации никуда.
Если это продукт - то его потроха ( типа методов классов ) не выдают.
А с библиотеками типа SDK я не сталкивался.

с.т.>> если подразумевается переиспользование и передача 3им лицам то без документации никуда.
yacc> Если это продукт - то его потроха ( типа методов классов ) не выдают.
yacc> А с библиотеками типа SDK я не сталкивался.

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

с.т.> а жц продукта учитывает то что команда разработки может смениться в какой-то момент и при этом нужно будет как минимум во время использования что-то с багами делать?
Тут хватит лидов/сеньоров и того что я описал
И да - баг-трекер и система версий - тоже как бы документ

yacc> Ну я программист.
yacc> И тоже слабого мнения относительно комментариев под каждым чихом.

А об этом речи и не было

yacc> Документировать имеет смысл диаграмму классов, инстанцирования и последовательности, а на это, как правило, нет времени - далее скетча/концепта дело обычно не идет, да и его хватает.

А также все методы и свойства внешнего API и некоторые методы и свойства внутреннего.

yacc> Назначение и логика простых методов видна прямо из кода.

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

yacc> А архитектура - повод для перманентных срачей, потому что каждый знает как лучше

Срачи - дело ущербных. Здоровые люди применяют тот подход, который принят у них в компании, и не делают мозгА другим.

с.т.> если подразумевается переиспользование и передача 3им лицам то без документации никуда.

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

Написание комментариев и тестов - это как изложение того же самого на ещё двух языках. В ходе такой проработки можно выявить слабые стороны архитектуры, которые не видны на вскидку из кода.

с.т.> в первую очередь пользовательской, эксплуатационной.

С этой точки зрения, полезно писать инструкции по эксплуатации. Чтобы потом можно было прикрыться от части "багов".

Zenitchik> А также все методы и свойства внешнего API и некоторые методы и свойства внутреннего.
Внутренний - и сами разберутся.
Внешний - только если проект типа фреймворка или библиотеки и именно это и продается.
Такие типы - редкость - на этом в РФ особо денег не заработаешь.

Zenitchik> Не все методы простые.
Сложные в комментируются только в той мере чтобы понять.
Длинных методов быть не должно.

Zenitchik>Кроме того, программы генерации документации составляют оную из комментариев.
Несколько диаграмм объясняет больше сотни этих сгенерированных мертвых томов.

Zenitchik> Следовательно, если мы хотим, чтобы в документации было описание метода - нужно написать таковое в комментарий.
Метод виден по своему исходнику.

Zenitchik> Срачи - дело ущербных. Здоровые люди применяют тот подход, который принят у них в компании
Да нифига. Текучка есть везде и взглядов разных полно.
Принимают стандарты кодирования - но это не архитектура.

yacc> Тут хватит лидов/сеньоров и того что я описал
Наблюдал результаты такого.. Разбухшая система, на которую все завязано, и в которой никто не знает, что как крутится, потому что старики ушли. Пробовали вешать задачи на кого-то из имеющихся - был завал, потому как тронешь что-то, костыли падают. Пробовали стороннюю компанию нанимать, платили денег как за пароход, итог примерно такой же.
В итоге ща кто-то возрастом за 70 сидит решает затыки, потому что понимает логику этой камасутры, а другая команда делает новый продукт на замену. Чтоб тот старый просто выкинуть.


yacc> И да - баг-трекер и система версий - тоже как бы документ
Который при большом обьеме багов никак не помогает..

с.т.>> если подразумевается переиспользование и передача 3им лицам то без документации никуда.
Zenitchik> Не только. Если проект большой - сотни мегабайт исходников, и ему многие годы, то порой возникают затруднения с пониманием работы старого кода.

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

Zenitchik> Написание комментариев и тестов - это как изложение того же самого на ещё двух языках. В ходе такой проработки можно выявить слабые стороны архитектуры, которые не видны на вскидку из кода.

особенно в ходе тестов. "ой а как-то оно медленно-херовато работает...а что это у нас ТААКОЕ?")) и вот тут то все косяки архитектуры и реализации и начинают вылазить.

с.т.>> в первую очередь пользовательской, эксплуатационной.
Zenitchik> С этой точки зрения, полезно писать инструкции по эксплуатации. Чтобы потом можно было прикрыться от части "багов".

ага.

в идельном случае ПМИ начинаем писаться сразу после ТЗ и аналитической проработки и всё это параллельно с разработкой MVP, допиливается - перепиливается (что бы как можно скорее до пром стенда с пром данными добежать) и идёт потом в комплект документации. и тогда инструкция по эксплуатации нормальная получается, на практическом опыте откатанная.

с.т.>>> если подразумевается переиспользование и передача 3им лицам то без документации никуда.
Zenitchik>> Не только. Если проект большой - сотни мегабайт исходников, и ему многие годы, то порой возникают затруднения с пониманием работы старого кода.

КО подсказывает,что шапки с комментариями вышли из моды лет 10 назад, сейчас наоборот в Питоне код часто вообще без комментариев, все комментарии - в 1-м месте или в readme.txt. Читаемость и логичность кода часто важнее комментариев, но и с этим бывает беда : индийские методики и зашифрованный код, который надо хакать, чтобы понять, где тут рабочий фрагмент, а где оболочка.

Zenitchik> Вы боретесь с ветряными мельницами. Я говорю "комментарии", а имею в виду "описание API, данное в комментариях".
Про описание API я вообще не говорю: это необходимая часть работоспособного кода. Если код по своему назначению должен вызываться снаружи, то описания вызовов столь же необходимы для его использования и реальной работы, как и сам код.

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


Zenitchik> Кроме этого, в комментариях может находиться название применённого алгоритма, или его краткое описание, если он сильно нестандартный. Может какое-то уравнение, которое присутствует в коде в неявном виде, но чтобы было нагляднее - полезно записать в виде условия.
А вот это уже в опен-сурсе нечасто.

Татарин> Чтобы программист сделал подробную и реально годную документацию, его обычно нужно заставить. Что уже никак не вяжется с "коммунистической" мотивацией. И самый простой и надёжный способ инфорсировать - отношения "начальник-подчинённый" и материальная заинтересованность.
Я видел что-то более-менее документированное в тех проектах, где есть архитектор.
Писать программера доки - почти анреал. Особенно если скрам.

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

с.т.>>>> если подразумевается переиспользование и передача 3им лицам то без документации никуда.
Zenitchik>>> Не только. Если проект большой - сотни мегабайт исходников, и ему многие годы, то порой возникают затруднения с пониманием работы старого кода.
digger> КО подсказывает,что шапки с комментариями вышли из моды лет 10 назад, сейчас наоборот в Питоне код часто вообще без комментариев, все комментарии - в 1-м месте или в readme.txt. Читаемость и логичность кода часто важнее комментариев, но и с этим бывает беда : индийские методики и зашифрованный код, который надо хакать, чтобы понять, где тут рабочий фрагмент, а где оболочка.

ну питон питоном но разнообразные си джава и sql наврядли покинут мир кровавого энтерпрайза.

Татарин> Чтобы программист сделал подробную и реально годную документацию, его обычно нужно заставить. Что уже никак не вяжется с "коммунистической" мотивацией. И самый простой и надёжный способ инфорсировать - отношения "начальник-подчинённый" и материальная заинтересованность.

В целом - согласен.

Zenitchik>> Кроме этого, в комментариях может находиться название применённого алгоритма, или его краткое описание, если он сильно нестандартный. Может какое-то уравнение, которое присутствует в коде в неявном виде, но чтобы было нагляднее - полезно записать в виде условия.
Татарин> А вот это уже в опен-сурсе нечасто.

Но стремиться к этому нужно. Я не раз в собственных пэт-проектах сталкивался с вопросом "Что я, чёрт возьми, написал?!" и после этого описывал суть алгоритма.

digger> КО подсказывает,что шапки с комментариями вышли из моды лет 10 назад, сейчас наоборот в Питоне код часто вообще без комментариев, все комментарии - в 1-м месте или в readme.txt.

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

А в один файл их скрипт соберёт. Как это делается с JSDoc.

Zenitchik> КО подсказывает, что описания типов передаваемых параметров и возвращаемого значения должны находиться рядом с объявлением функции. В языках со статической типизацией это происходит автоматически, а в языках с динамической - приходится писать шапку из комментариев. И никакая мода этого не отменит.

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

digger> Дык не делают по факту : не модно, потому начальство не требует.Если названия параметров самоочевидные, то и не надо, по-хорошему комментируется только то, что неочевидно.

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

digger> Но по факту некомментированный и запутанный код встречается очень часто.

Ну, мы же стремимся к совершенству? Оставим плохих программистов с их проблемами


digger> Хуже отсутствия комментариев - избыточное использование классов и прочая инкапсуляция, когда полезный код разносится на разные куски и фиг поймешь, что оно делает и где баг.

Вы, кажется, пишете про антипаттерн "выстрел дробью"? К нему может приводить преждевременная оптимизация.

Zenitchik> Вы, кажется, пишете про антипаттерн "выстрел дробью"? К нему может приводить преждевременная оптимизация.

Нет, индийские алгоритмы кодописания, когда код преднамеренно запутывается и усложняется для демонстрации собственной важности. Финкция х * y раздергивается на 5 классов и их членов, занимает полдня понять, что это делает.