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

Question

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

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

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

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

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

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

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

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

Answer 1

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

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

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

Answer 2

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

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.

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

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

Answer 3

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

Answer 4

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

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

Answer 5

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

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

Answer 6

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

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

Answer 7

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

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

Answer 8

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

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

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

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

И т.д.

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

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

Answer 9

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

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

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

Answer 10

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

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

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)

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

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

Answer 11

По порядку:

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

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

Answer 12

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

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

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

Answer 13

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

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

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

Всего лишь моя щепотка соли...

Answer 14

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

Answer 15

Слышали ли вы о "ВЕБ-проекте" Дональда Кнута по реализации его Грамотное Программирование концепция?Это больше, чем самодокументирующийся код;это больше похоже на документацию, которая может быть скомпилирована и выполнена в виде кода.Хотя я не знаю, насколько широко он используется сегодня.

Answer 16

Разница заключается между "что" и "как".

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

Answer 17

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

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

Answer 18

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

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

Answer 19

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

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

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

Answer 20

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

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

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

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

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

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

Answer 21

Мое мнение изложено в этом посте:

Единственный совет по документированию вашего кода.

Отрывок:

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

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

Answer 22

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

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

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

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

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

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

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

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

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

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

Answer 23

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

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

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

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

Answer 24

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

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

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

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

Answer 25

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

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

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

Answer 26

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

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

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

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

Answer 27

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

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

Answer 28

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

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

Answer 29

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

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

Поиск пополам

Бинарный поиск

Бинарный магазин

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

Answer 30

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

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

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

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

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