Действительно ли я должен зарегистрировать свои закрытые методы? [закрытый]

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

ПЛОХО

private void Update(string sValue, DateTime dValue)
{...}

ЛУЧШЕ

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate)
{...}

А как насчет второй версии, которую нужно документировать? Имя определяет его цель, а имена параметров делают очевидным то, что предполагается передать.

Если ваши методы настолько длинные и сложные, что для их объяснения требуется роман, вам необходимо разбить их на логические части функциональности это может быть хорошо названо и сфокусировано. Это, IMHO, намного легче понять, чем некоторую плохо написанную встроенную документацию, которая может быть или не быть актуальной - я ВСЕГДА собираюсь прочитать весь код, чтобы убедиться, что он соответствует тому, что говорится в документации, и в большинстве случаев я предполагаю, что документация не поддерживается, и игнорирую ее.

У вас также должны быть модульные тесты, которые изменяют код и делают функциональность еще БОЛЕЕ очевидной. С хорошо названными классами, методами,

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

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

У меня есть привычка убирать плохую / бессмысленную документацию, потому что, как и интерфейс, нет ничего лучше плохого. хе-хе

Только если тебе нечем заняться. Поэтому - вероятно - нет.

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

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

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

Да. Я слышал эту шутку:

Программирование похоже на секс. Одна ошибка, и вы должны поддерживать ее до конца своей жизни.

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

Лично я больше верю в самодокументированный код, чем в документацию по коду. Интенсивное использование имен, раскрывающих намерение, функций без побочных эффектов и т. Д.

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

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

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

Edit: даже с резюме я бы не документировал. Частные методы могут измениться, прорасти заново, исчезнуть. Одним из основных принципов объектно-ориентированного программирования является инкапсуляция. Вам не нужно знать, что делает частный метод. А что касается разработчиков, кто будет поддерживать всю эту документацию в актуальном состоянии? Впервые, но в будущем?

Редактировать 2: Из комментариев

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

Я полностью согласен, но ... код не должен быть « умным », код должен быть функциональным и читаемым . В большинстве случаев вы должны стремиться к тому, чтобы ваш код был как можно более прозрачным для читателя. Если вам нужно его прокомментировать, вам следует подумать о том, чтобы сделать код более понятным, прежде чем нажимать javadoc (или что-то еще, что вы используете).

Изменить 3:

Что бы вы предпочли увидеть?

/**
*   This method doesn't do what you expect it to.
*   Below you will find a whole ream of impenetrable
*   code. Where there are bits that look that they do x, they don't
*   they do y. 
**/
private void someComplexInternalMethod()
{
     ...
     badly named variables
     comments to describe intent
     perhaps some out of date orphaned comments
     as code has been removed but comment remains

     ....
     ....
     looong methods 
}

private void WellNamedMethod()
{
     ...
     well named variables
     shorter method, highly cohesive
     self documenting
}

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

Документирование частных методов полезно для сопровождающих или вашего пакета (включая вас).

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

Совершенно верно. Всегда пишите код с предположением, что вы должны будете изменить его через два года. Краткое изложение метода - самое важное. Я могу'

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

По моему опыту, хорошая документация никогда не бывает пустой тратой времени.

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

Да, определенно. Через шесть месяцев вам, возможно, придется вернуться и провести ремонт. Пара хорошо размещенных комментариев может сэкономить вам много времени и усилий. Возможно, вам не нужно документировать это в той степени, в какой вы хотели бы использовать общедоступный API, но несколько комментариев никогда не повредят.

Да, да, да. Задокументируйте любой код, который вы пишете.

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

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

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

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

Я займу непопулярную позицию и скажу нет.

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

Документация должна поддерживаться и обновляться всякий раз, когда код изменяется. Теперь вы просите разработчика обслуживания дважды выполнить одну и ту же работу. Один раз для исправления ошибки и еще раз для объяснения исправления.

По моему опыту, второе действие часто не происходит. Когда я начинал здесь, я унаследовал кодовую базу 5-летней давности. В одном конкретном приложении комментировалось около половины всего, часто - ОЧЕНЬ часто - комментарии мало или совсем не походили на реальный код. Либо чувак был на кислоте, когда писал их, или он написал комментарии с первой частью кода, затем код изменился, а комментарии - нет.

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

Мы ожидаем, что разработчики смогут писать читаемый код, а новые сотрудники будут иметь возможность читать читаемый код.

А теперь давайте начнем голосование против!

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

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

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

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

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

Люди, которые проводят большую часть своего рабочего дня, читая большие объемы кода, являются командой: руководители и архитекторы, которые несут ответственность за поддержание работоспособности систем и ведут переговоры с руководством от имени своей группы (групп) разработчиков. Даже хорошо написанный код трудно читать быстро и в большом количестве, потому что основная его часть будет находиться на другом уровне абстракции от уровня, который интересует читателя.

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

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

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

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

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

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

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

What about private fields? For a Serializable class private fields must be documented. From "Effective Java" by Johsua Bloch:

Private fields define a public API, which is the serialized form of the class, and this public API must be documented. The presence of the @serial tag tells the Javadoc utility to place this documentation on a special page that documents serialized forms