Что такое самодокументированный код и может ли он заменить хорошо документированный код? [закрыто]


258

У меня есть коллега, который настаивает на том, что его код не нуждается в комментариях, это «самодокументирование».

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

Помоги мне понять его точку зрения.

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

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

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

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

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


118
Вы знаете, что меня действительно впечатляет? Вы не согласны с этим парнем, но вы просите понять <i> его </ i>, а не больше боеприпасов против него.
Каяко

14
Как история совершенно противоположного случая, у меня есть сотрудник, который пишет тонны документации: в каждом файле cpp она содержит руководство, содержащее, по крайней мере, пару десятков страниц о реализации и использовании предоставленных функций. Однако она пишет катастрофически длинные и сложные функции (отдельные функции с 8000 строками кода), не интуитивно понятные идентификаторы для переменных и функций и т. Д. По сравнению с ней, я бы взял кого-то, кто стремится написать самодокументированный код, который не работает комментарии в любой день, при условии, что его код хорошо организован с небольшими функциями, которые легко понять.
stinky472


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

2
Раньше я работал с кем-то, кто перекомментировал все, но обычно с бесполезными комментариями, вроде i++; // increment i- но без объяснения того, почему i следует увеличивать в этой точке функции.
nnnnnn

Ответы:


177

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

  • записывает комментарии документации (Doxygen, JavaDoc, комментарии XML и т. д.) для каждого класса, члена, типа и метода AND
  • четко комментирует любые части кода, которые не являются самодокументируемыми
  • записывает комментарий для каждого блока кода, который объясняет намерение или действия кода на более высоком уровне абстракции (т. е. найти все файлы размером более 10 МБ вместо циклического перебора всех файлов в каталоге, проверьте, не превышает ли размер файла более 10 МБ, вернуть доходность, если истина )

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


В соответствии с этим ответом, я думаю: memeagora.blogspot.com/2008/11/comments-code-smell.html
Маслоу

14
Точка №. 3 должно быть частью пункта №. 1 ИМХО, если метод настолько сложен, что требует больших комментариев абстракции для нескольких блоков кода, каждый такой блок кода должен быть новым методом.
Бьярке Фрейнд-Хансен

10
+1 для «не означает, что не должно быть никаких комментариев», что, кажется, мнение некоторых людей.
Skurmedel

4
Еще не нужно комментировать это: public static Collection <File> filesGreaterThan (путь к файлу, int sizeInBytes);
Trylks

6
Хорошее практическое правило для меня состоит в том, что комментарии никогда не должны объяснять, ЧТО делает код, но могут использоваться, чтобы объяснить ПОЧЕМУ это делает. Другими словами, прокомментируйте блок кода, чтобы объяснить, почему он есть, а не как он работает. Если вы можете выделить блок в его собственный метод с четким именем, то это даже лучше. Вот что такое самодокументированный код.
Мел

387

Ну, поскольку речь идет о комментариях и коде, давайте посмотрим на некоторый реальный код. Сравните этот типичный код:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

К этому самодокументированному коду, который показывает, что делается:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

А затем к этому документированному коду, который лучше объясняет, почему это делается:

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

И окончательная версия кода в виде документации с нулевыми комментариями:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

Вот пример плохого стиля комментирования:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

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


73
Однако весь этот кусок должен быть в функции с описательным именем;)
workmad3

7
Да, мне проще было бы прочитать функцию displacementDueToGravity (int timeInSeconds, float gravitationalAcceleration = 9.81).
Кристиан Ромо

18
Единственный комментарий, по которому я скучаю: почему 5 секунд?
Джон Нильссон

3
Еще один голос за название описательной функции. Это не дает само уравнение, но я не вижу, что это необходимо.
Лорен Печтел

18
Каковы единицы гравитационной силы? Существуют ограничения на то, сколько вы можете добавить к имени переменной. В какой-то момент вы должны объяснить, что вы пытаетесь сделать . Часто это не очевидно , поэтому вам необходимо комментировать код. Это абсолютная чушь сказать код документирован, это просто сам описательный .
Ник

172

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


Согласовано. Хотя иногда даже лучший код может скрыть, каков его конечный эффект, это решается путем ответа на вопрос «почему» в комментариях. Как в «Почему вы просто изменили эти 5 переменных таким образом?»
Сэм Эрвин

Мой 2 Cent: разве дело [Unit, Spec, Behavior,] не является ответом «почему на земле»? Тогда вы можете прочитать контрольный пример и понять, почему.
Джонке

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

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

2
@tsellon, ваша автоматизированная спецификация может сказать вам об этом, и что приятно, это код, который проверяет код реализации. Так что, если реализация как-то изменится, спецификация сломается. Как это мило? Комментарии, которые предупреждают вас, когда код реализации не выполняет то, что указано в комментарии?
Прагматичный Agilist

96

Кто-то однажды сказал

1) Пишите комментарии только для кода, который трудно понять.
2) Старайтесь не писать код, который трудно понять.


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

15
Я часто нахожу вещи, которые я написал в пятницу, довольно
трудными,

1
что заставляет нас «стараться не писать комментарии»
mustafabar

37

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

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


1
ИМХО Блок должен сказать вам, как , имя функции должно сказать вам, почему . Пока вы используете оба вместе, вы передаете и намерение и реализацию .... int GetBoundingBox() {return CalcContentDimensions() + this.padding + this.margin;}...
Basic

19

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

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

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


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

16

Я забыл, откуда я это взял, но:

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


26
Мусор. Хорошие комментарии в коде, безусловно, имеют свое место. Возьмите пример выбора между двумя одинаково правильными методами решения проблемы. Комментарий, объясняющий, почему один метод был выбран над другим, чрезвычайно важен, и вы никогда не сможете получить это из самого кода.
Скотт Дорман

7
Если есть два РАВНО ПРАВИЛЬНЫХ метода, то имеет ли значение, почему вы выбрали один из других?
EBGreen

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

Тогда, если ваши критерии принятия решения - скорость, они НЕ ПРАВИЛЬНО ПРАВИЛЬНЫ. Я не говорю, что комментарии плохие. Просто они необходимы, потому что в настоящее время нет такого языка программирования, который был бы настолько ясен и однозначен, что любой мог бы взглянуть на код и мгновенно узнать его намерения.
EBGreen

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

14

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

Самодокументированный код - это код, который не требует комментариев в свободном тексте для информированного читателя, чтобы понять, что он делает. Например, этот фрагмент кода самодокументируется:

print "Hello, World!"

и так это:

factorial n = product [1..n]

и так это:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

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

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


14

Самодокументированный код - хороший пример «СУХОГО» (не повторяйте себя). Не дублируйте информацию в комментариях, которая есть или может быть в самом коде.

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

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

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

И т.п.

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

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


4
Единственное исключение: плохие программисты. Я видел комментарии о том, что код делает то, чего нет. Тогда я спрашиваю себя: должен ли я исправить код или комментарий?
Гуге

Вы не можете превзойти имена методов в Objective-C. :)

13

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

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

Самодокументируемый код + необходимые комментарии будут иметь большое значение для помощи людям в командах.


9

Для того, чтобы:

  • Самодокументированный код - это код, который четко выражает свое намерение читателю.
  • Не совсем. Комментарии всегда полезны для комментариев о том, почему была выбрана конкретная стратегия. Тем не менее, комментарии, которые объясняют, что делает часть кода, указывают на код, который недостаточно самодокументирован и может использовать некоторый рефакторинг.
  • Комментарии врут и устаревают. Код всегда говорит , скорее всего, чтобы сказать правду.
  • Я никогда не видел случай , когда то , что кода не может быть сделана достаточно ясно без комментариев; однако, как я уже говорил ранее, иногда необходимо / полезно включать комментарий о причине .

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


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

Имена методов могут лгать и могут быть устаревшими.
Кальмарий

7

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

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

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

Просто моя щепотка соли ...


6

Например, рассмотрим следующий фрагмент:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

Если конечно, лучшая версия была бы:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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


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

6

Разница между «что» и «как».

  • Вы должны документировать «что» делает рутина.
  • Вы не должны документировать, «как» это делает, за исключением особых случаев (например, обратиться к конкретному алгоритму бумаги). Это должно быть самодокументировано.

Сильно не согласен. То, что делает рутина, должно быть ясно из названия. Как это происходит, должно быть очевидно из кода реализации. Почему реализация была написана как есть, должна быть задокументирована .
Энтони Мэннинг-Франклин

5

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


Вы принимаете это как правило, и в конечном итоге вы пишете учебник в своей базе кода ;-) Я согласен с неочевидными решениями.
Ддимитров

@ddimitrov, это хорошее наблюдение. Но, как вы говорите, для неочевидных решений (а обычно это те, которые действительно требуют документации в любом случае), это хорошая практика.
Онорио Катеначчи

Документируйте код, который не был написан! :)
Тони

5

В компании, где я работал, один из программистов прикрепил к ее монитору следующее.

«Документируй свой код, как тот, кто его поддерживает, - гомосексуальный маньяк, который знает, где ты живешь».


4

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

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

У меня когда-то был профессор, который твердо верил в эту теорию. На самом деле, самое лучшее, что я когда-либо помню, чтобы он говорил: «Комментарии для сестренок».
Сначала мы застали всех врасплох, но это имеет смысл.
Тем не менее, ситуация такова, что, хотя вы можете понимать, что происходит в коде, но кто-то менее опытный, чтобы вы могли идти за вами и не понимать, что происходит. Это когда комментарии становятся важными. Я знаю много раз, что мы не считаем их важными, но очень мало случаев, когда комментарии не нужны.


Затем рефакторинг, пока он не станет яснее. Я твердо убежден в том, что код ничего не может сказать достаточно ясно.
Tigraine

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

1
@scott: вы могли бы поместить оба варианта в больший класс и оставить другой нереализованным с комментарием о ... о, подождите.
Обезьяна

4

Я удивлен, что никто не привел в действие « Грамотное программирование », метод, разработанный в 1981 году Дональдом Кнутом из TeX и известностью «Искусство компьютерного программирования».

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

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

Я нашел пример в Интернете: http://moonflare.com/code/select/select.nw или HTML-версия http://moonflare.com/code/select/select.html.

Если вы можете найти книгу Кнута об этом в библиотеке (Дональд Э. Кнут, «Литературное программирование», Стэнфорд, Калифорния: Центр изучения языка и информации, 1992, CSLI Lecture Notes, № 27.), вам следует прочитать ее.

Это самодокументированный код, полный рассуждений и все. Даже делает хороший документ, Все остальное просто хорошо написано в комментариях :-)


Это на самом деле противоположность самодокументируемого кода. Текст для человека, код для машины. И на каком языке должен быть код? Сборка конечно. Людям не нужно читать это, верно? Им нужно только написать это!
Гуге

4

Я хотел бы предложить еще одну перспективу для многих действительных ответов:

Что такое исходный код? Что такое язык программирования?

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

Должны ли вы быть в состоянии прочитать то, что вы пишете?

Исходный код написан не на человеческом языке. Это было опробовано (например, FORTRAN), но это не совсем успешно.

Исходный код не может иметь двусмысленности. Вот почему мы должны придать ему больше структуры, чем мы делаем с текстом. Текст работает только с контекстом, который мы воспринимаем как должное, когда используем текст. Контекст в исходном коде всегда явный. Подумайте, «используя» в C #.

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

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

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

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


3

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

Для меня это правила, которым я стараюсь следовать:

  • Код должен быть максимально простым и понятным для чтения.
  • Комментарии должны содержать причины для принятия проектных решений, например: почему я использую этот алгоритм, или ограничения, которые имеет код, например: не работает, когда ... (это должно быть обработано в контракте / утверждении в коде) (обычно в рамках функции / процедуры).
  • Документация должна перечислять использование (вызывающие преобразования), побочные эффекты, возможные возвращаемые значения. Его можно извлечь из кода с помощью таких инструментов, как jDoc или xmlDoc. Поэтому обычно он находится за пределами функции / процедуры, но близко к коду, который он описывает.

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


3

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

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

Быть способным определить, что код выполняет X с первого взгляда, гораздо проще, чем определить, что код не выполняет Y. Он должен документировать Y ...

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


3

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

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

Изменить: Я (и, вероятно, все остальные), вероятно, должны иметь положение, что приложение цифровой обработки сигналов (DSP) должно быть очень хорошо прокомментировано. Это в основном потому, что приложения DSP, по сути, 2 для циклов, снабженных массивами значений, и добавляет / умножает / и т. Д. Указанные значения ... чтобы изменить программу, вы меняете значения в одном из массивов ... требуется пара комментариев, чтобы сказать, что вы делаете в таком случае;)


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

3

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

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

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

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


3

Я бы сказал - как многие из вас - что для подлинного самодокументирования код должен демонстрировать какую-то форму намерения. Но я удивлен, что никто не упомянул BDD - Behavior Driven Development . Отчасти идея заключается в том, что у вас есть автоматические тесты (код), объясняющие цель вашего кода, что иначе трудно сделать очевидным.

Хорошее доменное моделирование 
+ хорошие имена (переменные, методы, классы) 
+ примеры кода (модульные тесты из вариантов использования) 
= самодокументирующее программное обеспечение 

2

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

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

2

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

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

BisectionSearch

BinarySearch

BinaryChop

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


2

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

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

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

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

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


2

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


1

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

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


1

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

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

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

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

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.