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

Question

Допустим, у меня есть функция DisplayWhiskers (), которая помещает некоторые косые черты и обратную косую черту на экран, чтобы представить усики животного, подобные этому: /// \\\. Я мог бы написать комментарий для этой функции в соответствии с

// Represents an animal's whiskers by displaying three  
// slashes followed by a space and three backslashes

Но если я затем добавлю функции DisplayKitten () и DisplaySealion (), которые в рамках своей работы вызывают DisplayWhiskers (), сколько подробностей об отображении усов должно быть в комментариях к этим другим функциям?

С одной стороны, мне кажется, что я должен иметь возможность просматривать комментарии для DisplayKitten () и понимать все, что мне нужно, о том, что он собирается делать, включая то, как именно он будет отображать усы. Я не должен был идти в другое место, чтобы прочитать комментарии для DisplayWhiskers (), чтобы выяснить это.

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

Что считается лучшей практикой?

РЕДАКТИРОВАТЬ: Несколько ответов предположили, что решение заключается в чтении кода. Я понимаю принцип хорошего кода, который является его собственным лучшим комментарием, но для этого вопроса я имел в виду не комментарии внутри кода, а комментарии в заголовочных файлах, которые сопровождают прототипы функций. Давайте предположим, что реальный код предварительно скомпилирован и недоступен для клиента, который хочет использовать или вызвать его.

Answer 1

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

Answer 2

В общем, комментарии не должны концентрироваться на том, что делает код - сам код документирует это. Вместо этого они должны сосредоточиться на том, ПОЧЕМУ все делается.

Answer 3

Я бы сказал, что в целом этот пункт находится на правильном пути в 99% случаев:

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

То, как DisplayKitten () вызывает DisplayWhiskers (), и даже тот факт, что он вызывает его, - это, вероятно, деталь реализации.

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

Answer 4

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

Answer 5

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

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

Просто скажите потенциальным абонентам, что им нужно знать, например: displayKitten () на самом деле отображает котенка? Если да, то где? Или он возвращает строковое представление?

Должны ли вы дать формат? Это зависит от. Является ли фактическое представление котенка деталью реализации, как описано в вопросе? В этом случае нет, вы не должны давать формат. Но если это соответствует какой-либо спецификации, рекомендуется указывать спецификацию - возможно, даже в названии метода: displayKittenPerFsda246_a().

Answer 6

"для этого вопроса я имел в виду не комментарии в коде, а комментарии в файлах заголовков, которые сопровождают прототипы функций."

Вы, вероятно, получите разные ответы, если замените слово «комментарии» словом «документация» во всем вопросе. Я думаю, что это дополнение очень сильно меняет вопрос.

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

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

Answer 7

оставить комментарии СУХОЙ

Answer 8

В идеале ваши функции должны выполнять только одну вещь, какой бы ни была «вещь» и на каком уровне детализации.

Точно так же они должны быть описаны на соответствующем уровне детализации. Если вы распечатываете котенка ASCII, вы можете оставить это как описание для DisplayKitten(). Вам не нужно описывать все, что он делает.

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

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

Answer 9

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