Как стать автором
Обновить

Комментарии 12

Про javadoc глупость какая-то написана. Я хоть и не разработчик, но не так давно надо было править старый монолит и именно благодаря javadoc удалось легко найти необходимый метод и исправить.

Также допущение о доступности исходного кода звучит странно. А если исходники не доступны, то как смотреть на javadoc? Его достаточно легко экспортировать и отдать вместе с продуктом. Опять же, когда над кодом может работать множество людей, javadoc хоть как-то организует разработчиков одинакого документировать код.
Про javadoc там написано с жизненным примером (пусть и на пайтоне :-). Подавляющее большинство тех, что я видел, выглядели как-то так:
 /**
  * Gets a customer
  *
  * @param customerId customer's id
  * @return Customer 
  */
Customer getCustomer(int customerId) {
      . . .
}

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

Как раз питону джавадока не хватает, только вместо очевидных заметок писать надо типы и поведение при разных типах.

Не лучше ли писать типы в type hints?

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

Разумеется, все, что нельзя выразить в типе — нужно записать в пояснении; просто зачем туда тащить формальный тип, он ведь не будет проверятся.

Формальный тип тащить не надо в общем случае, но он может быть частью формата, и тогда от этого никуда не денешься. Как, например, в PhpDoc.

Такой комментарий не должен проходить ревью.

Такие комментарии иногда след предварительного планирования работы.

Javadoc — самый бесполезный

если не нравиться, не пользуйтесь. Javadoc полезен тем, что не надо постоянно читать код. Многие IDE прекрасно с ним работают.
Вот пример хорошего комментария
Часто можно услышать совет «пишие комменте ПОЧЕМУ, а не ЧТО». Хотя это, вероятно, охватывает большинство моих комментариев, это не то, как я думаю о том, когда комментировать. Вместо этого я обычно пишу комментарий, когда есть что-то особенно сложное, либо в домене, либо в том, как выполняется реализация.

С философской точки зрения каждая строчка кода содержит техдолг по дальнейшей поддержке. Ценность представляет только конечный функционал. И если можно его реализовать вообще без единой строчки, то все идеально. В противном случае у вас всегда должен быть мотив "ПОЧЕМУ"/"ДЛЯ ЧЕГО" вы ее добавили. Теоретически этот мотив и следует указывать в комментарии. Вопрос "ЧТО" как правило решается осмысленными идентификаторами классов, методов и переменных. Вопрос "КАК" должен быть понятен из самого кода (тоже теоретически).


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

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


Есть еще такой момент: зачастую коментарии требуются не конкретному куску кода, а всему реализуемому функционалу. Для этого неплохо подходит файл package-info.java. Однако очень редко вижу, чтобы кто-то его использовал, за исключением самой JDK. А вот адепты TDD сказали бы, что в этом случае коментариями должны быть тесты.


Javadoc — самый бесполезный

Он не бесполезен, а неудобен. Неудобны теги, форматирование (звездочки вначале), html. Более адекватным для этих целей был бы Markdown.

Такое чувство что автор не пишет код.
документация к приватному методу может вполне содержать инфу для чего выделили этот метод и что он делает.
Да бывает что пишут дубликат, но это скорее заглушка, но никто не мешает указать причину почему принято то или иное решение.
Автору статьи (Генри) надо просто научиться извлекать пользу.
потому что вполне может быть String location, а в комменте может быть написано, location format: xxxxx, пример не очень удачный, но все же.
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.