Комментарии 56
1. Что мешает вместе с правкой кода править документацию?
2. Что мешает просто описать все это в документации?
3. А строчка @return formatted address это что7
4. Там, как мне кажется, должно быть описание того, какие параметры функция принимает.
Говно, короче.
2. Что мешает просто описать все это в документации?
3. А строчка @return formatted address это что7
4. Там, как мне кажется, должно быть описание того, какие параметры функция принимает.
Говно, короче.
1. Ничто не мешает, и тем не менее очень часто люди это не делают. Это факт. Забывают, не успевают, не знают — причин может быть масса.
2. см. 1.
3. Это стандартный javadoc. @param — параметры функции, @return — что она возвращает.
2. см. 1.
3. Это стандартный javadoc. @param — параметры функции, @return — что она возвращает.
Какая связь между вопросом «как надо делать» и тем, что какие-то люди что-то забывают, не успевают, или просто им влом?
Самая прямая. Чем сложнее правила, тем сложнее их выполнять. Лучше сделать правила максимально простыми, тогда скорее люди их будут выполнять. В идеале правила должны выполняться «сами по себе», что и достигается с помощью автоматического запуска юнит-тестов при каждой компиляции проекта.
Тесты тоже должны меняться. А где гарантия, что человек забивающий на комментарии, не забьет на тесты? Тесты не панация их тоже пишут люди и от ложных срабатываний никто не застрахован.
Здрасьте!
Как раз здесь и зарыта собака! Юнит-тесты запускаются автоматически при каждой компиляции проекта, вот вам и гарантия. Забил на тесты — тесты не прошли — проект не собрался.
Одним словом, в отличие от документации, юнит-тесты валидируются. Цена за это — они не совсем на человеческом языке.
Как раз здесь и зарыта собака! Юнит-тесты запускаются автоматически при каждой компиляции проекта, вот вам и гарантия. Забил на тесты — тесты не прошли — проект не собрался.
Одним словом, в отличие от документации, юнит-тесты валидируются. Цена за это — они не совсем на человеческом языке.
Ага привет!
Не все тесты одинаково полезны. Да пофиг, что не начеловеческом, их все равно пишут люди. И в них точно так же могут быть ошибки, как изначально заложенные, так и те которые появится в связи с изменением логики функции.
Положите пятку на грудь и поклянитесь, что не возможна ситуация когда ледячий программер перепищит функцию, закомитит и даже CI подтвердит, что все зашибись, а потом выяснится, что они из 300 тестов имеит ложное срабатывание(цифра с потолка, чем больше раздолюбайство, тем больше) или на что то не будет тестов, тут вон давече проскакивал текст как при 100% покрытие оказывается, не все в тестох то учтено. Ну и по закону подлости это будет в самом идиотском месте.
Юнит-тесты, очень хорошая практика, но совсем не панация, особенно в руках нерадивых товарищей.
Ревью кода, при котором проверяются юнит-тесты и комментарии как часть кода, спасет отца росейской демократии, от посылания его к чертовой матери.
Не все тесты одинаково полезны. Да пофиг, что не начеловеческом, их все равно пишут люди. И в них точно так же могут быть ошибки, как изначально заложенные, так и те которые появится в связи с изменением логики функции.
Положите пятку на грудь и поклянитесь, что не возможна ситуация когда ледячий программер перепищит функцию, закомитит и даже CI подтвердит, что все зашибись, а потом выяснится, что они из 300 тестов имеит ложное срабатывание(цифра с потолка, чем больше раздолюбайство, тем больше) или на что то не будет тестов, тут вон давече проскакивал текст как при 100% покрытие оказывается, не все в тестох то учтено. Ну и по закону подлости это будет в самом идиотском месте.
Юнит-тесты, очень хорошая практика, но совсем не панация, особенно в руках нерадивых товарищей.
Ревью кода, при котором проверяются юнит-тесты и комментарии как часть кода, спасет отца росейской демократии, от посылания его к чертовой матери.
1. Что мешает при кодинге копипастом заменить часть кода в остальных одинаковых кусках, если мы его заменили в одном?
>1. Что мешает вместе с правкой кода править документацию?
Есть такая поговорка, если на стене висит ружье, то оно обязательно когда-нибудь выстрелит. Этот подход принципиально граблеориентированный, он не гарантирует автоматической подгонки доков под изменившуюся сигнатуру функции
Есть такая поговорка, если на стене висит ружье, то оно обязательно когда-нибудь выстрелит. Этот подход принципиально граблеориентированный, он не гарантирует автоматической подгонки доков под изменившуюся сигнатуру функции
Ага и для того, чтобы понять что делает метод, надо либо просматривать его, либо смотреть тест? Прочитайте раздел из Совершенного кода про комментирование.
А какая разница, смотреть javadoc или смотреть юнит-тесты? Если IDE умеет показывать и то и другое — не вижу разницы.
Возможно, javadoc легче читать, поскольку он написан на человеческом языке, но нет никакой гарантии, что там написана правда. That's the point.
Возможно, javadoc легче читать, поскольку он написан на человеческом языке, но нет никакой гарантии, что там написана правда. That's the point.
javadoc смотреть не надо, у меня будет документация в читабельном формате, сгенерированная.
А описание юнит тестами сейчас действительно становится популярно. Берешь опенсорсную библиотеку, хочешь ее использовать, а документации нет. Нафига она мне, автор же выложил юнит-тесты к исходникам… Если раньше писали: «что тяжело в исходниках самому посмотреть?», то теперь аналогично пишут про юнит-тесты.
А описание юнит тестами сейчас действительно становится популярно. Берешь опенсорсную библиотеку, хочешь ее использовать, а документации нет. Нафига она мне, автор же выложил юнит-тесты к исходникам… Если раньше писали: «что тяжело в исходниках самому посмотреть?», то теперь аналогично пишут про юнит-тесты.
НЛО прилетело и опубликовало эту надпись здесь
>Зачем дьявол придумал javadoc
Зачем всякие личности рассуждают о том, чего не понимают?
Зачем всякие личности рассуждают о том, чего не понимают?
Юнит-тесты — это для Вашего кода, для того, чтобы Вы писали работающий код. Пользователю Ваших классов юнит-тесты ни к селу, ни к городу, ему нужна нормальная документация, а юнит-тесты зачастую лежат отдельно от библиотеки, которую просто надо использовать, а не исследовать!
Далее по списку… У Вашего метода есть тысячи вариантов поведения? Время, потраченное на написание этой «статьи» можно было использовать для продумывания нормальной архитектуры и столь необходимого в Вашем случае рефакторинга кода.
Захотелось что-то поменять в методе? Напомню, вы документируете API, который с самого рождения должен оставаться максимально неизменным, внутреняя же реализация метода ни его пользователям, ни читателям документации неинтересна — совсем необязательно в док-блоке описывать какая у Вас инструкция используется в третьей строчке метода!
Далее по списку… У Вашего метода есть тысячи вариантов поведения? Время, потраченное на написание этой «статьи» можно было использовать для продумывания нормальной архитектуры и столь необходимого в Вашем случае рефакторинга кода.
Захотелось что-то поменять в методе? Напомню, вы документируете API, который с самого рождения должен оставаться максимально неизменным, внутреняя же реализация метода ни его пользователям, ни читателям документации неинтересна — совсем необязательно в док-блоке описывать какая у Вас инструкция используется в третьей строчке метода!
Абсолютно правильно.
И вообще, если в коде комментариев больше, чем собственно кода — гнать программера в шею. Это уже не код, а маразм.
И вообще, если в коде комментариев больше, чем собственно кода — гнать программера в шею. Это уже не код, а маразм.
Пожалуй, у меня речь скорее не об API, а о «внутреннем» коде, пишушемся внутри компании, «пользователями» которого являются сами же программисты. Я так понимаю, по вашей философии, его вообще не надо документировать? Ну вот, я об этом.
Всё, что написано красным цветом, превращаем в название метода
А если там хотя бы 5-7 строчек?
А если там хотя бы 5-7 строчек?
значит разделить на 5-7 методов
Ясное дело, это не абсолютная истина, возможны исключения и тд, но вообще — подход «вместо обширных комментариев делаем нормальные названия методов + пишем юнит-тесты» мне нравится, это так-то классика рефакторинга (Фаулер и тд), и мне вот лично не понятно, почему все отзываются отрицательно об этом.
Ясное дело, это не абсолютная истина, возможны исключения и тд, но вообще — подход «вместо обширных комментариев делаем нормальные названия методов + пишем юнит-тесты» мне нравится, это так-то классика рефакторинга (Фаулер и тд), и мне вот лично не понятно, почему все отзываются отрицательно об этом.
НЛО прилетело и опубликовало эту надпись здесь
Ага, соглашусь, и начинаю понимать реакцию — в статье наезд на документацию, а не на комментарии.
Но вот вопрос насчет сгенеренной таким образом (через docstring'и — или как это в java называется) документации — интересный и неоднозначный (см., например, jacobian.org/writing/great-documentation/ и jacobian.org/writing/great-documentation/what-to-write/).
Но вот вопрос насчет сгенеренной таким образом (через docstring'и — или как это в java называется) документации — интересный и неоднозначный (см., например, jacobian.org/writing/great-documentation/ и jacobian.org/writing/great-documentation/what-to-write/).
It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.
Don’t.
Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation.
There’s no substitute for documentation written, organized, and edited by hand.
НЛО прилетело и опубликовало эту надпись здесь
Чтбы не рассуждать об абстрактных программистах, пренебрежем всеми «правилами ведения спора» и перейдем на личности и конкретные примеры. Чтобы никого не обижать, буду ругать себя)
Писал я, значит, документацию к pymorphy (морфологический анализатор на python). И в некотрых разделах положился на docstring'и. В нашем контексте — это тот же javadoc, только для питона (там много своих особенностей, но они сейчас к делу не относятся). И получился, как сейчас понимаю, полный трэш ( packages.python.org/pymorphy/api.html ). Это, по-моему, невозможно читать. Я на самом деле старался. Я радовался, что не нужно писать документацию руками — написал комментарии, и готова документация. И мне сначала результат понравился. Но потом стало понятно, что сам никогда не буду заглядывать в эти разделы документации — гораздо проще заглянуть в исходник (да и поддержка со стороны IDE для этого есть сразу). Эти сгенерированные разделы никак не помогают понять архитектуру проекта, выявить места, которые можно оптимизировать, да и вообще, понять, как всем пользоваться-то. Там все в кучу, и написано это непонятно для кого. Архитектуру проекта, как его использовать и тд. можно понять, читая другие разделы, которые структурировались «руками» (например, packages.python.org/pymorphy/django_api.html).
В других проектах — то же самое было. Делаешь, кажется, что нормально, но использовать в итоге катастрофически невозможно. Более отвратительно написанной документации, чем в django-photo-albums, еще поискать нужно. Там куча текста, который по-отдельности-то весь правильный и поясняющий что-то, но, прочитав который целиком, глобально понять нельзя абсолютно ничего (мой респект, если кто-то разобрался все-таки). Это яркий пример документации, собранной по принципу javadoc. Это ужасно)
В итоге перестал полагаться на авто-сгенеренную документацию, и пишу теперь «руками». Мне кажется, выходит короче, быстрее даже, и гораздо понятнее (напр., документация к django-robokassa )
Возможно, у нас разные какие-то предпосылки: по-моему, человек, который пишет документацию и не понимает код — дикость, да и с требованиями вроде «писать по ГОСТ» никогда не сталкивался (и, надеюсь, не столкнусь). Не хотелось бы никого обижать, и, возможно, чего-то я не понимаю, но это, вообщем-то, как раз и напоминает «About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation.»
Писал я, значит, документацию к pymorphy (морфологический анализатор на python). И в некотрых разделах положился на docstring'и. В нашем контексте — это тот же javadoc, только для питона (там много своих особенностей, но они сейчас к делу не относятся). И получился, как сейчас понимаю, полный трэш ( packages.python.org/pymorphy/api.html ). Это, по-моему, невозможно читать. Я на самом деле старался. Я радовался, что не нужно писать документацию руками — написал комментарии, и готова документация. И мне сначала результат понравился. Но потом стало понятно, что сам никогда не буду заглядывать в эти разделы документации — гораздо проще заглянуть в исходник (да и поддержка со стороны IDE для этого есть сразу). Эти сгенерированные разделы никак не помогают понять архитектуру проекта, выявить места, которые можно оптимизировать, да и вообще, понять, как всем пользоваться-то. Там все в кучу, и написано это непонятно для кого. Архитектуру проекта, как его использовать и тд. можно понять, читая другие разделы, которые структурировались «руками» (например, packages.python.org/pymorphy/django_api.html).
В других проектах — то же самое было. Делаешь, кажется, что нормально, но использовать в итоге катастрофически невозможно. Более отвратительно написанной документации, чем в django-photo-albums, еще поискать нужно. Там куча текста, который по-отдельности-то весь правильный и поясняющий что-то, но, прочитав который целиком, глобально понять нельзя абсолютно ничего (мой респект, если кто-то разобрался все-таки). Это яркий пример документации, собранной по принципу javadoc. Это ужасно)
В итоге перестал полагаться на авто-сгенеренную документацию, и пишу теперь «руками». Мне кажется, выходит короче, быстрее даже, и гораздо понятнее (напр., документация к django-robokassa )
Возможно, у нас разные какие-то предпосылки: по-моему, человек, который пишет документацию и не понимает код — дикость, да и с требованиями вроде «писать по ГОСТ» никогда не сталкивался (и, надеюсь, не столкнусь). Не хотелось бы никого обижать, и, возможно, чего-то я не понимаю, но это, вообщем-то, как раз и напоминает «About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation.»
Не могу сказать, что JavaDoc — это плохо и только плохо. Например, сейчас в своем проекте использую Google Guava. Это библиотека с открытыми исходниками, которые я подключил в свой проект. Так что при случае, если у меня возникают вопросы о том, как работает тот или иной метод, я спокойно могу заглянуть в код. Но тем не менее JavaDoc'ом пользуюсь, т.к. он отображает только публичные методы и дает сжатое представление о классе в целом. Особенно это оказалось полезным, когда только-только начинал с ней работать и не представлял, где искать ту или иную функциональность. Внутри многие классы довольно сложные, с большим числом внутренних классов и методов, многие из которых не являются public, так что разбираться только по коду было бы очень неудобно.
А так по большому счету хороший метод хорош еще и тем, что по его названию, названию его параметров и типу результата будет и так понятно, что он делает. Вопросы могут возникнуть касательно тонкостей реализации (например, «ленив» ли метод или нет), побочных эффектов, а такие вещи редко меняются.
А так по большому счету хороший метод хорош еще и тем, что по его названию, названию его параметров и типу результата будет и так понятно, что он делает. Вопросы могут возникнуть касательно тонкостей реализации (например, «ленив» ли метод или нет), побочных эффектов, а такие вещи редко меняются.
В корне не согласен. Не говоря о том, что toString — это стандартный метод, который вызывается, например, при попытке вывести объект в консоль. Дело в другом: если пишется класс не для одного лишь проекта, но для повторного использования, а тем более — для выкладывания в общий доступ, то необходимость javadoc не вызывает сомнений. Сколько раз я сталкивался с мощными библиотеками с рудиментарными комментариями или вообще без них (практечески всегда от их использования приходилось отказываться в пользу аналогов с более вменяемой документацией). «Говорящие» методы необходимы, но не достаточны.
Мы говорим немножко о разных вещах. Вы говорите о документации для публично доступных библиотек — это такой отдельный продукт, который компания отдельно создаёт. В этом случае проверка корректности такой документации — отдельная статья расходов.
Я же говорю о «внутреннем» коде, к которому программеры пишут документацию просто так, просто потому что так принято или Eclipse автоматически её генерирует. А потом её никто не валидирует, и она очень быстро устаревает. Документация лжёт — этим всё сказано.
Я же говорю о «внутреннем» коде, к которому программеры пишут документацию просто так, просто потому что так принято или Eclipse автоматически её генерирует. А потом её никто не валидирует, и она очень быстро устаревает. Документация лжёт — этим всё сказано.
>корректности такой документации — отдельная статья расходов
А написание тестов не отдельная статья расходов?
А написание тестов не отдельная статья расходов?
Конечно, написание тестов занимает какое-то время.
Но я убеждён, что оно себя окупает с лихвой за счёт меньшего количества ошибок, понятности кода и т.д. и т.п. Я использую это на практике, так что я знаю, о чём говорю.
Есть распространённое мнение, что «нам не до тестов», но я вас уверяю, так говорят только те, кто не пробовал их на практике.
Но я убеждён, что оно себя окупает с лихвой за счёт меньшего количества ошибок, понятности кода и т.д. и т.п. Я использую это на практике, так что я знаю, о чём говорю.
Есть распространённое мнение, что «нам не до тестов», но я вас уверяю, так говорят только те, кто не пробовал их на практике.
Я бы сказал, что проблема всё-таки не в документации, а в людях. Документация устаревает, если принцип работы метода сильно меняется, а тот кто модифицировал, поленился обновить. С изменением принципа работы метода сталкиваюсь в своей работе крайне редко. А вот с забывчивостью по поводу элементарного форматирования собственного кода перед коммитом — практически каждый божий день.
Я чуток позанудствую на тему того что данный статический toString с параметрами ничего общего со стандартным не имеет, окромя вводящего в заблуждение имени.
Смотрите в сторону jakarta commons у них отличная javadoc документация. А делать тесты еще можно для простых вещей, но когда у проекта куча нестандартных входов и выходов, то просто кошмар. Если бы я еще, помимо кода, занимался сложными тестами, то сроки разработки моих проектов выросли бы в полтора-два раза. Но мне конечно проще, ибо я один над кодом работаю.
Но это не значит, что сложные тесты лишние, но считаю, что для таких вещей нужно отдельных специалистов нанимать или выращивать. Т.е. чтобы они брали код и писали для него тесты и javadoc документацию (она тоже очень нужна). Из-за этого стоимость разработки вырастит, но проект будет содержать меньше ошибок и будет более гибок к изменениям.
P.S. Помнится на phpclub были разработчики, года 3 назад, когда еще читал тот форум. Они там делали CMS и убеждали, что тесты = документация. Но опытные программеры пытались объяснить, что это не так. В общем, не надо впадать в крайности.
Но это не значит, что сложные тесты лишние, но считаю, что для таких вещей нужно отдельных специалистов нанимать или выращивать. Т.е. чтобы они брали код и писали для него тесты и javadoc документацию (она тоже очень нужна). Из-за этого стоимость разработки вырастит, но проект будет содержать меньше ошибок и будет более гибок к изменениям.
P.S. Помнится на phpclub были разработчики, года 3 назад, когда еще читал тот форум. Они там делали CMS и убеждали, что тесты = документация. Но опытные программеры пытались объяснить, что это не так. В общем, не надо впадать в крайности.
Речь идёт о юнит-тестах. Они как раз должны проверять только саму функцию без затрагивания внешних зависимостей. И это должны делать сами девелоперы.
А то, о чём вы говорите — это integration tests. Для этого действительно нужны отдельные специалисты. Но это совсем другая область.
PS. Кто сказал, что именно те программеры были опытными, а не наоборот?
А то, о чём вы говорите — это integration tests. Для этого действительно нужны отдельные специалисты. Но это совсем другая область.
PS. Кто сказал, что именно те программеры были опытными, а не наоборот?
Итого имеем:
— «вполне старательный программист» — индус в плохом смысле слова, не обученый давать вменяемые имена методам.
— Приёмки кода нет или она фиктивна, иначе бы этот «toString» был завёрнут из-за несоответствия имени и выполняемых действий. В более-менее нормальной компании даже использование не общепринятых сокращений не приветствуется.
— Похоже, что обязательного написания юнит-теста перед реализацией новой функциональности ни кто не требует. Т.е. в бардак процессе разработки.
— Тимлид отсутствует или нанят для того, что бы пить кофе, а за порядком в коде и за тем, что бы разработчики поддерживали комментарии в актуальном состоянии не следит.
Так при чём тут JavaDoc?
— «вполне старательный программист» — индус в плохом смысле слова, не обученый давать вменяемые имена методам.
— Приёмки кода нет или она фиктивна, иначе бы этот «toString» был завёрнут из-за несоответствия имени и выполняемых действий. В более-менее нормальной компании даже использование не общепринятых сокращений не приветствуется.
— Похоже, что обязательного написания юнит-теста перед реализацией новой функциональности ни кто не требует. Т.е. в бардак процессе разработки.
— Тимлид отсутствует или нанят для того, что бы пить кофе, а за порядком в коде и за тем, что бы разработчики поддерживали комментарии в актуальном состоянии не следит.
Так при чём тут JavaDoc?
>>Боюсь только, что наш доблестный программист, вернувшись с кухни, фокуса не поймёт, ведь он не видел наших волшебных движений. Ему снесёт башню от одного только факта, что его комментарии КТО-ТО НАГЛО ПОТЁР, и он постарается нас найти и уничтожить за такую подрывную деятельность. А его кофе тем временем остынет. Ну что ж, и то неплохо: ведь кофе, говорят, вреден. Значит, одно хорошее дело мы всё-таки сегодня сделали.
Судя по всему еще и не дружит с системами контроля версий.
Судя по всему еще и не дружит с системами контроля версий.
Автор частично прав. Комментарии, бесспорно, более чем полезны.
Однако, весьма часто (90% случаев, включая коммерческие проекты) эти комментарии выглядят примерно так (выдуманный пример на js):
function openFile(fileName, options)
документация:
function openFile opens file, returns file handler
fileName: name of file
options: array of options
За примером далеко ходить не надо, кто писал на ExtJS первой версии (так же частично относится и ко второй) знает, что большинство документации было именно в этом стиле (справедливо стоит заметить, что в 3й версии документация очень хороша).
Резюмируя: не стоит думать что комментарии — это некий golden hammer, который моментально следает плохой код — хорошим.
Однако, весьма часто (90% случаев, включая коммерческие проекты) эти комментарии выглядят примерно так (выдуманный пример на js):
function openFile(fileName, options)
документация:
function openFile opens file, returns file handler
fileName: name of file
options: array of options
За примером далеко ходить не надо, кто писал на ExtJS первой версии (так же частично относится и ко второй) знает, что большинство документации было именно в этом стиле (справедливо стоит заметить, что в 3й версии документация очень хороша).
Резюмируя: не стоит думать что комментарии — это некий golden hammer, который моментально следает плохой код — хорошим.
Автор, а вам не надоело почти на каждый камент отвечать, что вас не так поняли. Мысль ваша проясняется после чтения комментариев. Мне кажется стоит статью пока в черновики и дописать на основе комментариев.
Во-первых, большинство IDE заточено на быстрое подключение и показ JavaDoc-а (даже в тех случаях когда у вас отсутствуют исходники).
Во-вторых, у Unit-тестов «быстрого просмотра» в IDE не наблюдается. Соответственно, пока вы будете лазать по юнит-тестам, я уже 10 строк кода напишу.
В-третьих, у вас пример неправильный. Там явно должно быть описание формата. Для примера приведу SimpleDateFormat. А вот такой JavaDoc вы уже никакими Unit-тестами не замените, так как код для тестирования будет занимать больше места, чем JavaDoc.
PS: Методы и переменные действительно нужно называть «говорящими» названиями. И без Unit-тестов работать совсем хреново. А JavaDoc я пишу в основном для сложных методов, принцип работы которых сам боюсь забыть через неделю.
Во-вторых, у Unit-тестов «быстрого просмотра» в IDE не наблюдается. Соответственно, пока вы будете лазать по юнит-тестам, я уже 10 строк кода напишу.
В-третьих, у вас пример неправильный. Там явно должно быть описание формата. Для примера приведу SimpleDateFormat. А вот такой JavaDoc вы уже никакими Unit-тестами не замените, так как код для тестирования будет занимать больше места, чем JavaDoc.
PS: Методы и переменные действительно нужно называть «говорящими» названиями. И без Unit-тестов работать совсем хреново. А JavaDoc я пишу в основном для сложных методов, принцип работы которых сам боюсь забыть через неделю.
При комментировании кода предполагается, что изменение кода будет тут же задокументировано. А «неуспел», «забыл», «другой разработчик» — это все отговорки для того, чтобы не документировать код
Выжимка из личного опыта разработки.
Комментарии нужны в следующих случаях:
1) Для участков кода, которые планируется потом переписать (не было времени, решил оставить коммент, а потом отрефакторить).
2) Для внешнего API какой-либо подсистемы или технологии. Это действует только для продуманного API (приведу в пример J2SE API). Если API создается а-ля «тут и так все понятно, зачем минимизировать интерфейс? Даешь гибкость!», то комментарии не работают.
3) Для библиотек классов, ориентированных на наследование другими разработчиками. В этом случае иногда не спасает даже наличие исходников, потому что необходимо четко понимать, из каких соображений разработчик поместил в базовый класс тот или иной метод, а на такой анализ уходит очень много драгоценного времени.
4) Для верхнеуровнего описания алгоритма или бизнес-операции. Хороший пример: вначале пишем верхнеуровневым псевдокодом (практически человеческий язык), потом каждую часть псевдокода кодируем, а сам псевдокод становится комментарием.
5) Для описания сложных участков, возникших в результате оптимизации. Если для целей оптимизации пришлось пренебречь понятностью, необходимо также предложить понятный вариант.
6) Требование заказчика. В этом случае дернуться особо некуда. Единственное — имеет смысл убедить его, что нужно документировать в соответствии с вышеописанными пунктами, и не более того. Иначе получим documentation hell.
Комментарии категорически НЕ нужны, когда:
1) Комментарий описывает КАК сделано, а не ЧТО и ДЛЯ ЧЕГО сделано.
2) Принятая структура документирования (например, JavaDOC) навязывает описание тех частей, которые и так понятны (например, параметры метода).
3) Комментарий описывает непонятную логику. В этом случае имеет смысл все переписать, а не комментировать.
4) Комментарии отражают части длинного алгоритма. В этом случае имеет смысл вынести эти части в отдельные методы. Очень часто при этом необходимость в комментариях отпадает.
P.S. В понимании всего вышенаписанного очень помогает книжка «Совершенный код».
Комментарии нужны в следующих случаях:
1) Для участков кода, которые планируется потом переписать (не было времени, решил оставить коммент, а потом отрефакторить).
2) Для внешнего API какой-либо подсистемы или технологии. Это действует только для продуманного API (приведу в пример J2SE API). Если API создается а-ля «тут и так все понятно, зачем минимизировать интерфейс? Даешь гибкость!», то комментарии не работают.
3) Для библиотек классов, ориентированных на наследование другими разработчиками. В этом случае иногда не спасает даже наличие исходников, потому что необходимо четко понимать, из каких соображений разработчик поместил в базовый класс тот или иной метод, а на такой анализ уходит очень много драгоценного времени.
4) Для верхнеуровнего описания алгоритма или бизнес-операции. Хороший пример: вначале пишем верхнеуровневым псевдокодом (практически человеческий язык), потом каждую часть псевдокода кодируем, а сам псевдокод становится комментарием.
5) Для описания сложных участков, возникших в результате оптимизации. Если для целей оптимизации пришлось пренебречь понятностью, необходимо также предложить понятный вариант.
6) Требование заказчика. В этом случае дернуться особо некуда. Единственное — имеет смысл убедить его, что нужно документировать в соответствии с вышеописанными пунктами, и не более того. Иначе получим documentation hell.
Комментарии категорически НЕ нужны, когда:
1) Комментарий описывает КАК сделано, а не ЧТО и ДЛЯ ЧЕГО сделано.
2) Принятая структура документирования (например, JavaDOC) навязывает описание тех частей, которые и так понятны (например, параметры метода).
3) Комментарий описывает непонятную логику. В этом случае имеет смысл все переписать, а не комментировать.
4) Комментарии отражают части длинного алгоритма. В этом случае имеет смысл вынести эти части в отдельные методы. Очень часто при этом необходимость в комментариях отпадает.
P.S. В понимании всего вышенаписанного очень помогает книжка «Совершенный код».
Точно также можно обосновать не желание писать любую документацию. Она быстро устареет, а подновить ее забудут. Ну ее нафиг.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Зачем дьявол придумал javadoc