Необходимо ли писать комментарий Javadoc для КАЖДОГО параметра в сигнатуре метода?

Один из разработчиков в моей команде считает, что необходимо написать комментарий javadoc для КАЖДОГО параметра в сигнатуре метода. Я не думаю, что это необходимо, и на самом деле я думаю, что это может быть даже вредно.

Прежде всего, я думаю, что имена параметров должны быть описательными и самодокументируемыми. Если не сразу понятно, для чего нужны ваши параметры, вы, вероятно, делаете это неправильно. Тем не менее, я понимаю, что иногда неясно, для чего предназначен параметр, поэтому в этих случаях, да, вы должны написать комментарий Javadoc, объясняющий параметр.

Но я думаю, что нет необходимости делать это для КАЖДОГО параметра. Если уже очевидно, для чего предназначен параметр, комментарий javadoc является избыточным; Вы просто создаете дополнительную работу для себя. Кроме того, вы создаете дополнительную работу для тех, кто должен поддерживать ваш код. Методы со временем меняются, и поддержка комментариев почти так же важна, как и поддержка вашего кода. Сколько раз вы видели комментарий типа «X делает Y по причине Z» только для того, чтобы увидеть, что комментарий устарел, и на самом деле метод даже не принимает параметр X? Это происходит постоянно, потому что люди забывают обновлять комментарии. Я бы сказал, что вводящий в заблуждение комментарий более вреден, чем вообще никакой комментарий. И, таким образом, существует опасность чрезмерного комментирования: создавая ненужную документацию, вы

Однако я уважаю другого разработчика в моей команде и признаю, что, возможно, он прав, а я неправ. Вот почему я задаю вам вопрос, коллеги-разработчики: действительно ли необходимо написать комментарий Javadoc для КАЖДОГО параметра? Предположим, что этот код является внутренним для моей компании и не будет использоваться какой-либо внешней стороной.

Аннотации Javadoc (и, по словам Microsoft, XMLDoc) - это не комментарии , а документация .

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

Документация представляет собой договор между блоком кода и его абонентами. Это часть публичного API. Всегда предполагайте, что Javadoc / XMLdoc попадет либо в файл справки, либо во всплывающее окно автозаполнения / intellisense / дополнения кода, и будет замечено людьми, которые не проверяют внутренности вашего кода, а просто хотят использовать его для каких-то целей. их.

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

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

Или комментируйте все или ничего не комментируйте (очевидно, что комментировать все гораздо лучше). Подумайте о ком-то, кто использует ваш код, просматривая ваш API непосредственно в исходном файле или в сгенерированном файле doc (т.е. вывод doxygen). Несоответствия, как правило, приводят к путанице, которая приводит к тому, что время, затрачиваемое на поиск источника, выясняет, почему что-то не было прокомментировано, что приводит к потере времени, которого можно было бы избежать, если бы параметр был только что прокомментирован в первую очередь.

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

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

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

Так что это означает, что разработчики не должны тратить время на документирование самоочевидных параметров и возвращаемых значений, верно?

Ну, давай разберемся.

Если мы все документируем, предполагая, что предельные комментарии действительно тривиальны и не требуют обдумывания или исследования, то добавляется время, чтобы фактически напечатать комментарий и исправить опечатки.

Если мы выбираем, то расходы:

• Наличие и победа в споре с другими разработчиками в вашей команде, которые считают, что все должно быть задокументировано.
• Для каждого параметра определяется, следует ли это документировать.
• Больше споров с вашей командой, когда у кого-то другое мнение о том, должен ли был задокументирован параметр.
• Потратьте время на поиски кода и исследования, когда параметр, который считается самоочевидным, оказывается не таким.

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

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

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

Не забывайте, что javadoc можно сделать видимым, в то время как отдельно от кода, главным примером является сам Java API . Не включая javadoc для каждого параметра в метод, вы неверно представляете метод и то, как его можно использовать.

«необходимо» является полностью субъективным. Я думаю, что вы спрашиваете, «в вашей ситуации, если вы добавите комментарий Javadoc». Не зная объема или контекста вашего приложения, как мы узнаем, что подходит для вас?

Если этот общедоступный код (т. Е. Код, предназначенный для доступа других пользователей, например, API), тогда да, задокументируйте каждый параметр. Не думайте, что читатель знает о проекте столько же, сколько и вы. Но в остальном вам и вашей команде решать самим.