Подтвердить что ты не робот

Должен ли я документировать свои личные методы?

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

4b9b3361

ОТВЕТЫ

Ответ 1

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

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

Ответ 2

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

Ответ 3

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

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

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

Ответ 4

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

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

Ответ 5

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

Ответ 6

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

Ответ 7

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

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

Ответ 8

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

Ответ 9

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

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

Изменить 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
}

Ответ 10

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

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

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

Ответ 11

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

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

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

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

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

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

Теперь давайте начнем вниз!

Ответ 12

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

Ответ 13

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

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

Ответ 14

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

Ответ 15

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

BAD

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

ЛУЧШЕ

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

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

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

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

Ответ 16

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

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

Ответ 17

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

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

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

Ответ 18

Только если вам нечего делать. Поэтому - возможно - нет.

Ответ 19

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

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

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

Ответ 20

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

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

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

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

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

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

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

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

Ответ 21

Как насчет частных полей? Для класса Serializable частные поля должны быть документированы. Из "Эффективной Java" Йохса Блоха:

Частные поля определяют открытый API, который представляет собой сериализованную форму класса, и эта публикация API должен быть документирован. Присутствие тега @serial сообщает утилите Javadoc разместить эту документацию на специальной странице, которая документирует сериализованные формы