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

Question

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

Answer 1

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

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

Answer 2

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

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

Edit 2: Из комментариев

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

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

Edit 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 
} 

Answer 3

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

Answer 4

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

Answer 5

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

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

Answer 6

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

Answer 7

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

Answer 8

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

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

Answer 9

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

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

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

Answer 10

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

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

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

Answer 11

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

BAD

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

ЛУЧШЕ

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

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

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

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

Answer 12

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

Answer 13

Да.В качестве этой шутки я услышал:

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

Answer 14

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

Answer 15

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

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

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

Answer 16

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

Answer 17

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

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

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

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

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

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

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

Answer 18

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

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

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

Answer 19

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

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

Answer 20

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

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

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

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

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

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

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

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

Answer 21

А как насчет частных полей? Для класса Serializable личные поля должны быть задокументированы. От «Эффективного Java» по Johsua Блох:

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