Зачем дьявол придумал javadoc

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

    Компания SUN даже придумала специальный формат javadoc — «стандарт для документирования классов Java». В моей практике было совершенно обычным явлением, когда какой-то код не проходил Code Review, потому что в нём у некоторых методов отсутствовали комментарии.

    Я утверждаю, что этот подход устарел, и сегодня я расскажу, почему комментарии — это зло.



    Пример из жизни


    Это реальный код, написанный в 2010 году вполне старательным программистом, который не поленился и написал комментарий к своему методу. Довольный собой, но пошёл налить себе чашечку кофе из аппарата, а мы давайте-ка пока посмотрим, что же тут у нас есть.
    public class AddressUtil {
    /**
    * Format string as address, expected input
    * format:"EE ; ;Tallinn;Narva mnt;120B;831;10127"

    *
    * @param flatAddress
    * @return Formatted address

    */
    public static String toString(String flatAddress) {......}
    }

    Отлично! У нас есть корректно оформленный комментарий в формате javadoc, из которого специальная программа сможет сгенерировать HTML-документацию. По нему легко можно понять, что (теоретически) делает этот метод.

    Где же спрятался дьявол?


    Но где же те мелочи, в которых спрятался дьявол? А вот они:
    • Очень скоро эта документация устареет, потому что придёт другой девелопер и поменяет код, но забудет поменять документацию. Это может быть даже тот же самый девелопер, потому что пока он стоял в очереди за кофе, ему пришло в голову, что он забыл обработать один редкий случай. Вернувшись, он добавит нужный IF в код, но забудет о том, что у него уже есть javadoc, который необходимо поддерживать.
    • В документации не описаны масса случаев: как поведёт себя метод, если на входе придёт null или пустая строка? Что, если в адресе есть номер дома, но нет номера квартиры (то есть буржуй занял дом целиком)? Что там за пустой параметр между «EE» и «Tallinn»?
    • В документации нет ни слова о том, что этот метод возвращает.
    • В документации есть целых три лишних строчки: "*", "@param flatAddress" и "@return Formatted address". Только подумайте: они занимают большую часть документации, и они абсолютно бесполезны!


    Волшебство


    А теперь давайте поиграем в волшебников и превратим несколько цветных кусочков в гирлянду. Сделаем несколько магических пассов. Сим-салябим, Ахалай-махалай, Ляськи-масяськи…
    • Пасс номер 1: Всё, что написано красным цветом, превращаем в название метода: toString -> formatAddress.
    • Пасс номер 2: Всё, что написано синим цветом, переносим в юнит-тест.
    • Пасс номер 3: (мой любимый) Весь текст, написанный зелёным цветом — … правильно, стираем. Навсегда. Не жалейте его, он зря появился на свет!
    Что у нас получилось в итоге?
    public class AddressUtil {
    public static String formatAddress(String flatAddress) {......}

    @Test public void testFormatAddress() {
    assertEquals("Narva mnt 120B-831 10127 Tallinn",
    AddressUtil.formatAddress("EE ; ;Tallinn;Narva mnt;120B;831;10127"));
    }

    }

    Чем же новый вариант лучше старого?
    • Он тупо КОРОЧЕ: было 8 строк, стало 4.
    • Этот тест никогда не устареет, т.к. он будет запускаться автоматически каждый раз при сборке проекта, и если программист поменяет код, а о методе забудет, это сразу всплывёт.
    • Можно описать все редкие случаи: пустые строки, отсутствующие параметры, недопустимые значения и т.д.

    Одним словом,


    ХОРОШЕЕ НАЗВАНИЕ + ТЕСТЫ = ДОКУМЕНТАЦИЯ

    а точнее, «запускаемая документация» (executable documentation), то есть документация, которую можно не просто читать, но ещё и «запускать», автоматически проверяя, что она всё ещё адекватна.

    Говорят, у Конфуция над кроватью висел плакат:

    Convert comments to executable documentation

    Послесловие


    Боюсь только, что наш доблестный программист, вернувшись с кухни, фокуса не поймёт, ведь он не видел наших волшебных движений. Ему снесёт башню от одного только факта, что его комментарии КТО-ТО НАГЛО ПОТЁР, и он постарается нас найти и уничтожить за такую подрывную деятельность. А его кофе тем временем остынет. Ну что ж, и то неплохо: ведь кофе, говорят, вреден. Значит, одно хорошее дело мы всё-таки сегодня сделали.



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


    Андрей Солнцев

    Поделиться публикацией
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама
    Комментарии 56
    • +7
      1. Что мешает вместе с правкой кода править документацию?
      2. Что мешает просто описать все это в документации?
      3. А строчка @return formatted address это что7
      4. Там, как мне кажется, должно быть описание того, какие параметры функция принимает.

      Говно, короче.
      • +3
        1. Ничто не мешает, и тем не менее очень часто люди это не делают. Это факт. Забывают, не успевают, не знают — причин может быть масса.
        2. см. 1.
        3. Это стандартный javadoc. @param — параметры функции, @return — что она возвращает.
        • +2
          Какая связь между вопросом «как надо делать» и тем, что какие-то люди что-то забывают, не успевают, или просто им влом?
          • +6
            Самая прямая. Чем сложнее правила, тем сложнее их выполнять. Лучше сделать правила максимально простыми, тогда скорее люди их будут выполнять. В идеале правила должны выполняться «сами по себе», что и достигается с помощью автоматического запуска юнит-тестов при каждой компиляции проекта.
            • –1
              Тесты тоже должны меняться. А где гарантия, что человек забивающий на комментарии, не забьет на тесты? Тесты не панация их тоже пишут люди и от ложных срабатываний никто не застрахован.
              • 0
                Здрасьте!
                Как раз здесь и зарыта собака! Юнит-тесты запускаются автоматически при каждой компиляции проекта, вот вам и гарантия. Забил на тесты — тесты не прошли — проект не собрался.
                Одним словом, в отличие от документации, юнит-тесты валидируются. Цена за это — они не совсем на человеческом языке.
                • 0
                  Ага привет!
                  Не все тесты одинаково полезны. Да пофиг, что не начеловеческом, их все равно пишут люди. И в них точно так же могут быть ошибки, как изначально заложенные, так и те которые появится в связи с изменением логики функции.
                  Положите пятку на грудь и поклянитесь, что не возможна ситуация когда ледячий программер перепищит функцию, закомитит и даже CI подтвердит, что все зашибись, а потом выяснится, что они из 300 тестов имеит ложное срабатывание(цифра с потолка, чем больше раздолюбайство, тем больше) или на что то не будет тестов, тут вон давече проскакивал текст как при 100% покрытие оказывается, не все в тестох то учтено. Ну и по закону подлости это будет в самом идиотском месте.

                  Юнит-тесты, очень хорошая практика, но совсем не панация, особенно в руках нерадивых товарищей.

                  Ревью кода, при котором проверяются юнит-тесты и комментарии как часть кода, спасет отца росейской демократии, от посылания его к чертовой матери.
                  • 0
                    На эту тему актуально высказывание «Читай код».
        • –1
          1. Что мешает при кодинге копипастом заменить часть кода в остальных одинаковых кусках, если мы его заменили в одном?
          • +1
            Я немного не понял, к чему этот вопрос.
            Но ответ тот же: технически ничего не мешает, но факт в том, что люди этого не делают.
            • 0
              а вопрос не вам был)
              а ответ правильный. в том же ж и суть
            • 0
              Насяльниканама больнама сделаит.
            • +3
              >1. Что мешает вместе с правкой кода править документацию?

              Есть такая поговорка, если на стене висит ружье, то оно обязательно когда-нибудь выстрелит. Этот подход принципиально граблеориентированный, он не гарантирует автоматической подгонки доков под изменившуюся сигнатуру функции
            • +5
              Ага и для того, чтобы понять что делает метод, надо либо просматривать его, либо смотреть тест? Прочитайте раздел из Совершенного кода про комментирование.
              • –1
                А какая разница, смотреть javadoc или смотреть юнит-тесты? Если IDE умеет показывать и то и другое — не вижу разницы.

                Возможно, javadoc легче читать, поскольку он написан на человеческом языке, но нет никакой гарантии, что там написана правда. That's the point.
                • +1
                  javadoc смотреть не надо, у меня будет документация в читабельном формате, сгенерированная.

                  А описание юнит тестами сейчас действительно становится популярно. Берешь опенсорсную библиотеку, хочешь ее использовать, а документации нет. Нафига она мне, автор же выложил юнит-тесты к исходникам… Если раньше писали: «что тяжело в исходниках самому посмотреть?», то теперь аналогично пишут про юнит-тесты.
                  • –1
                    > у меня будет документация в читабельном формате, сгенерированная.
                    Повторюсь: нет никакой гарантии, что там написана правда, то какой толк от этой документации?
                    Опенсоурсные библиотеки — немного другой случай, я как бы не о нём говорил.
                  • НЛО прилетело и опубликовало эту надпись здесь
                    • –1
                      Да, я именно о внутреннем коде и говорю. Эта «немного другая» тема и есть моя тема. :)
                      • НЛО прилетело и опубликовало эту надпись здесь
                • +4
                  >Зачем дьявол придумал javadoc
                  Зачем всякие личности рассуждают о том, чего не понимают?
                  • +6
                    Юнит-тесты — это для Вашего кода, для того, чтобы Вы писали работающий код. Пользователю Ваших классов юнит-тесты ни к селу, ни к городу, ему нужна нормальная документация, а юнит-тесты зачастую лежат отдельно от библиотеки, которую просто надо использовать, а не исследовать!
                    Далее по списку… У Вашего метода есть тысячи вариантов поведения? Время, потраченное на написание этой «статьи» можно было использовать для продумывания нормальной архитектуры и столь необходимого в Вашем случае рефакторинга кода.
                    Захотелось что-то поменять в методе? Напомню, вы документируете API, который с самого рождения должен оставаться максимально неизменным, внутреняя же реализация метода ни его пользователям, ни читателям документации неинтересна — совсем необязательно в док-блоке описывать какая у Вас инструкция используется в третьей строчке метода!
                    • 0
                      Абсолютно правильно.

                      И вообще, если в коде комментариев больше, чем собственно кода — гнать программера в шею. Это уже не код, а маразм.
                      • –1
                        Пожалуй, у меня речь скорее не об API, а о «внутреннем» коде, пишушемся внутри компании, «пользователями» которого являются сами же программисты. Я так понимаю, по вашей философии, его вообще не надо документировать? Ну вот, я об этом.
                      • 0
                        Всё, что написано красным цветом, превращаем в название метода

                        А если там хотя бы 5-7 строчек?
                        • +2
                          значит разделить на 5-7 методов

                          Ясное дело, это не абсолютная истина, возможны исключения и тд, но вообще — подход «вместо обширных комментариев делаем нормальные названия методов + пишем юнит-тесты» мне нравится, это так-то классика рефакторинга (Фаулер и тд), и мне вот лично не понятно, почему все отзываются отрицательно об этом.
                          • НЛО прилетело и опубликовало эту надпись здесь
                            • +1
                              Ага, соглашусь, и начинаю понимать реакцию — в статье наезд на документацию, а не на комментарии.

                              Но вот вопрос насчет сгенеренной таким образом (через 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.
                              • НЛО прилетело и опубликовало эту надпись здесь
                                • +2
                                  Чтбы не рассуждать об абстрактных программистах, пренебрежем всеми «правилами ведения спора» и перейдем на личности и конкретные примеры. Чтобы никого не обижать, буду ругать себя)

                                  Писал я, значит, документацию к 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.»
                                  • НЛО прилетело и опубликовало эту надпись здесь
                        • +1
                          Не могу сказать, что JavaDoc — это плохо и только плохо. Например, сейчас в своем проекте использую Google Guava. Это библиотека с открытыми исходниками, которые я подключил в свой проект. Так что при случае, если у меня возникают вопросы о том, как работает тот или иной метод, я спокойно могу заглянуть в код. Но тем не менее JavaDoc'ом пользуюсь, т.к. он отображает только публичные методы и дает сжатое представление о классе в целом. Особенно это оказалось полезным, когда только-только начинал с ней работать и не представлял, где искать ту или иную функциональность. Внутри многие классы довольно сложные, с большим числом внутренних классов и методов, многие из которых не являются public, так что разбираться только по коду было бы очень неудобно.

                          А так по большому счету хороший метод хорош еще и тем, что по его названию, названию его параметров и типу результата будет и так понятно, что он делает. Вопросы могут возникнуть касательно тонкостей реализации (например, «ленив» ли метод или нет), побочных эффектов, а такие вещи редко меняются.
                          • +1
                            В корне не согласен. Не говоря о том, что toString — это стандартный метод, который вызывается, например, при попытке вывести объект в консоль. Дело в другом: если пишется класс не для одного лишь проекта, но для повторного использования, а тем более — для выкладывания в общий доступ, то необходимость javadoc не вызывает сомнений. Сколько раз я сталкивался с мощными библиотеками с рудиментарными комментариями или вообще без них (практечески всегда от их использования приходилось отказываться в пользу аналогов с более вменяемой документацией). «Говорящие» методы необходимы, но не достаточны.
                            • –2
                              Мы говорим немножко о разных вещах. Вы говорите о документации для публично доступных библиотек — это такой отдельный продукт, который компания отдельно создаёт. В этом случае проверка корректности такой документации — отдельная статья расходов.

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

                                А написание тестов не отдельная статья расходов?
                                • 0
                                  Конечно, написание тестов занимает какое-то время.
                                  Но я убеждён, что оно себя окупает с лихвой за счёт меньшего количества ошибок, понятности кода и т.д. и т.п. Я использую это на практике, так что я знаю, о чём говорю.

                                  Есть распространённое мнение, что «нам не до тестов», но я вас уверяю, так говорят только те, кто не пробовал их на практике.
                                  • 0
                                    Замените слова тест, на слово комментарий и почитайте, что получится.

                                    Если не забивать отверткой гвозди, то это оказывается удобный инструмент. Нужны и юнит-тесты и комментарии, перекосы это плохо.
                                • 0
                                  Я бы сказал, что проблема всё-таки не в документации, а в людях. Документация устаревает, если принцип работы метода сильно меняется, а тот кто модифицировал, поленился обновить. С изменением принципа работы метода сталкиваюсь в своей работе крайне редко. А вот с забывчивостью по поводу элементарного форматирования собственного кода перед коммитом — практически каждый божий день.
                                • +1
                                  Я чуток позанудствую на тему того что данный статический toString с параметрами ничего общего со стандартным не имеет, окромя вводящего в заблуждение имени.
                                • 0
                                  Смотрите в сторону jakarta commons у них отличная javadoc документация. А делать тесты еще можно для простых вещей, но когда у проекта куча нестандартных входов и выходов, то просто кошмар. Если бы я еще, помимо кода, занимался сложными тестами, то сроки разработки моих проектов выросли бы в полтора-два раза. Но мне конечно проще, ибо я один над кодом работаю.

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

                                  P.S. Помнится на phpclub были разработчики, года 3 назад, когда еще читал тот форум. Они там делали CMS и убеждали, что тесты = документация. Но опытные программеры пытались объяснить, что это не так. В общем, не надо впадать в крайности.
                                  • 0
                                    Речь идёт о юнит-тестах. Они как раз должны проверять только саму функцию без затрагивания внешних зависимостей. И это должны делать сами девелоперы.
                                    А то, о чём вы говорите — это integration tests. Для этого действительно нужны отдельные специалисты. Но это совсем другая область.

                                    PS. Кто сказал, что именно те программеры были опытными, а не наоборот?
                                  • +3
                                    Итого имеем:

                                    — «вполне старательный программист» — индус в плохом смысле слова, не обученый давать вменяемые имена методам.

                                    — Приёмки кода нет или она фиктивна, иначе бы этот «toString» был завёрнут из-за несоответствия имени и выполняемых действий. В более-менее нормальной компании даже использование не общепринятых сокращений не приветствуется.

                                    — Похоже, что обязательного написания юнит-теста перед реализацией новой функциональности ни кто не требует. Т.е. в бардак процессе разработки.

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

                                    Так при чём тут JavaDoc?
                                    • 0
                                      >>Боюсь только, что наш доблестный программист, вернувшись с кухни, фокуса не поймёт, ведь он не видел наших волшебных движений. Ему снесёт башню от одного только факта, что его комментарии КТО-ТО НАГЛО ПОТЁР, и он постарается нас найти и уничтожить за такую подрывную деятельность. А его кофе тем временем остынет. Ну что ж, и то неплохо: ведь кофе, говорят, вреден. Значит, одно хорошее дело мы всё-таки сегодня сделали.

                                      Судя по всему еще и не дружит с системами контроля версий.
                                    • 0
                                      Автор частично прав. Комментарии, бесспорно, более чем полезны.
                                      Однако, весьма часто (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, который моментально следает плохой код — хорошим.
                                      • 0
                                        Автор, а вам не надоело почти на каждый камент отвечать, что вас не так поняли. Мысль ваша проясняется после чтения комментариев. Мне кажется стоит статью пока в черновики и дописать на основе комментариев.
                                        • 0
                                          дык насколько я понял повествование: Автор пишет не используетй жавадок для приватных методов, описывайте юнитестами :) Остальных видимо клинит, так как они не очень понимаю зачем на прайват методах нужен жавадок :)
                                          • 0
                                            Надоело. Понял. Сделал.
                                            Я тут впервые, обвыкаюсь.
                                          • 0
                                            Во-первых, большинство IDE заточено на быстрое подключение и показ JavaDoc-а (даже в тех случаях когда у вас отсутствуют исходники).

                                            Во-вторых, у Unit-тестов «быстрого просмотра» в IDE не наблюдается. Соответственно, пока вы будете лазать по юнит-тестам, я уже 10 строк кода напишу.

                                            В-третьих, у вас пример неправильный. Там явно должно быть описание формата. Для примера приведу SimpleDateFormat. А вот такой JavaDoc вы уже никакими Unit-тестами не замените, так как код для тестирования будет занимать больше места, чем JavaDoc.

                                            PS: Методы и переменные действительно нужно называть «говорящими» названиями. И без Unit-тестов работать совсем хреново. А JavaDoc я пишу в основном для сложных методов, принцип работы которых сам боюсь забыть через неделю.
                                            • 0
                                              Да, есть такое. Но вот Intellij IDEA, например, умеет так же быстро и юнит-тесты показывать. Когда такая поддержка будет во всех IDE, то это преимущество javadoc перед юнит-тестами исчезнет. Так что это всего лишь вопрос техники.
                                            • 0
                                              При комментировании кода предполагается, что изменение кода будет тут же задокументировано. А «неуспел», «забыл», «другой разработчик» — это все отговорки для того, чтобы не документировать код
                                              • 0
                                                Нужен инструмент, который бы по рукам бил хотя-бы за неправильное описание сигнатуры функции. Вроде бы в doxygen'е что-то такое просматривалось.
                                                Еще бы хорошо иметь в руках автоматический генератор этих самых заготовок для доков.
                                              • 0
                                                Выжимка из личного опыта разработки.

                                                Комментарии нужны в следующих случаях:
                                                1) Для участков кода, которые планируется потом переписать (не было времени, решил оставить коммент, а потом отрефакторить).
                                                2) Для внешнего API какой-либо подсистемы или технологии. Это действует только для продуманного API (приведу в пример J2SE API). Если API создается а-ля «тут и так все понятно, зачем минимизировать интерфейс? Даешь гибкость!», то комментарии не работают.
                                                3) Для библиотек классов, ориентированных на наследование другими разработчиками. В этом случае иногда не спасает даже наличие исходников, потому что необходимо четко понимать, из каких соображений разработчик поместил в базовый класс тот или иной метод, а на такой анализ уходит очень много драгоценного времени.
                                                4) Для верхнеуровнего описания алгоритма или бизнес-операции. Хороший пример: вначале пишем верхнеуровневым псевдокодом (практически человеческий язык), потом каждую часть псевдокода кодируем, а сам псевдокод становится комментарием.
                                                5) Для описания сложных участков, возникших в результате оптимизации. Если для целей оптимизации пришлось пренебречь понятностью, необходимо также предложить понятный вариант.
                                                6) Требование заказчика. В этом случае дернуться особо некуда. Единственное — имеет смысл убедить его, что нужно документировать в соответствии с вышеописанными пунктами, и не более того. Иначе получим documentation hell.

                                                Комментарии категорически НЕ нужны, когда:
                                                1) Комментарий описывает КАК сделано, а не ЧТО и ДЛЯ ЧЕГО сделано.
                                                2) Принятая структура документирования (например, JavaDOC) навязывает описание тех частей, которые и так понятны (например, параметры метода).
                                                3) Комментарий описывает непонятную логику. В этом случае имеет смысл все переписать, а не комментировать.
                                                4) Комментарии отражают части длинного алгоритма. В этом случае имеет смысл вынести эти части в отдельные методы. Очень часто при этом необходимость в комментариях отпадает.

                                                P.S. В понимании всего вышенаписанного очень помогает книжка «Совершенный код».
                                                • 0
                                                  Точно также можно обосновать не желание писать любую документацию. Она быстро устареет, а подновить ее забудут. Ну ее нафиг.
                                                  • 0
                                                    Вы не путайте. Я жё чётко показываю, что мной движет не лень. Я предлагаю не отказаться от документации, а преобразовать её в другой вид, а именно, в юнит-тесты.
                                                    • –1
                                                      Ага представляю себе, юнит тесты на JDK вполне тянет на анекдот.
                                                      • 0
                                                        О чём вы? Какой анекдот? Где тут должно быть смешно?

                                                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.