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

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

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

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

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

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

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

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

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

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

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

Every comment in a program is like an apology to the reader. "I'm sorry that my code is so opaque that you can't understand it by looking at it". We just have to accept that we are not perfect but strive to be perfect and go right on apologizing when we need to.

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

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

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

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

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

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

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

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

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

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

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

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

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

Я думаю, дело в правильном количестве документации, а не во всей или ее части. Если параметры функции хорошо названы, вам часто не нужно точно говорить, что они собой представляют, например char * CustomerName довольно очевидно. Если вы используете диапазоны утвержденных значений для параметров, вам также не нужно документировать эти диапазоны. ИМО, документация должна охватывать все, что не так очевидно и, следовательно, требует некоторого объяснения, а для большей части кода требуется некоторая документация. Лично я предпочитаю видеть иллюстративный пример того, как работает данная функция, чем описательную документацию, в большинстве случаев.

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

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

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

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

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

Я бы перевернул это.

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

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

Во-первых, рассмотрим следующий фрагмент:

/**
 * 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;
 }

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

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

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

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

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

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

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

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.

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

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

Чтобы:

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

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

Вот мои лучшие ответы на ваши вопросы.

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

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

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

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

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

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

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

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

//For example, the above text deals with what is a useful comment

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

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

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)

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

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

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

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

1) Only write comments for code that's hard to understand.
2) Try not to write code that's hard to understand.

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

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

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

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

И т.п.

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

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

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

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

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

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

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

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

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

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

Разделение пополам

BinarySearch

BinaryChop

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

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

Я не говорю «не комментируйте непонятный код». Я говорю «сделайте ваш код понятным».

Если вы каким-то образом оставите свой код неясным, потом воспользуется комментариями для компенсации.

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

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

Хотя ... Я действительно читал цитату, однажды приписываемую Биллу Гейтсу: «Код - это документация».

Иди разберись.

Я думаю, уместно спросить, является ли конкретная строка кода самодокументированной, но, в конце концов, если вы не понимаете структуру и функцию фрагмента кода, то в большинстве случаев комментарии не помогут. Возьмем, к примеру, фрагмент "правильно прокомментированного" кода 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);

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

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

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

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

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

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

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

Некоторые точки зрения из лагеря комментирующих.

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

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

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

1. эта информация должна быть включена в общую сопроводительную документацию
2. Мне нужно очистить мой код

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

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

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

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

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

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

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

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

• Никогда не создавайте «удивительного» кода. Т.е. не используйте глупые макросы для переопределения вещей и т. д. Не злоупотребляйте перегрузкой операторов, не пытайтесь быть умными в этом.
• Разделите код в нужном месте. Используйте правильные абстракции. Вместо встраивания скользящего буфера (буфера фиксированной длины с двумя указателями, в который элементы добавляются с одного конца и удаляются с другого), используйте абстракцию с собственным именем.
• Сохраняйте низкую сложность функций. Если он становится слишком длинным или сложным, попробуйте разделить его на другие функции.

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

Кажется, здесь очень смешанные входы :)

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

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

становится;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if

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

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

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

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

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

Однажды я работал с парнем, который собирался продать финансовый пакет крупной компании. Они настояли на том, чтобы он задокументировал исходный код, для которого он создал процедуру ассемблера на 30+ страниц, и сказал: «Это задокументировано, посмотрите» - затем он перешел на страницу 13, и там был комментарий «счетчик ударов на единицу». Отличный продукт, отличный разработчик, но ...

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

> 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)

Но мне, например, нужен контекст, чтобы понять это полностью.

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

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

Если этот словарь и синтаксис легко отображаются (путем определения классов, методов и т. д.) В код на компьютерном языке, то этот код может быть самодокументированным. Кроме того, IMO, был создан предметно-ориентированный язык. (И это мое грубое определение «декларативного».)

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

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

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

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

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

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

Сможете ли вы читать то, что пишете?

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

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

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

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

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

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

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

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

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

Разница в том, «что» и «как».

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

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

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