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

251
задан 6 revs, 4 users 98% 23 August 2011 в 06:30
поделиться

49 ответов

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

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

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

171
ответ дан OregonGhost 23 November 2019 в 02:53
поделиться

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

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

BisectionSearch

BinarySearch

BinaryChop

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

2
ответ дан MikeJ 23 November 2019 в 02:53
поделиться

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

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

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

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

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

2
ответ дан Pavel Feldman 23 November 2019 в 02:53
поделиться

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

  • код, на который Вы смотрите, был сгенерирован автоматически, и следовательно любые редактирования к коду могли бы быть ударены в следующий раз, когда проект компилируется
  • А, меньше простая реализация была обменяна за увеличение производительности (разворачивающий цикл, создав таблицу поиска для дорогого вычисления, и т.д.)
2
ответ дан John 23 November 2019 в 02:53
поделиться

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

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 
3
ответ дан Torbjørn 23 November 2019 в 02:53
поделиться

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

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

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

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

3
ответ дан comingstorm 23 November 2019 в 02:53
поделиться

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

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

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

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

6
ответ дан ulm 23 November 2019 в 02:53
поделиться

Кто-то когда-то сказал

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

93
ответ дан Loofer 23 November 2019 в 02:53
поделиться

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

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

36
ответ дан Scott Dorman 23 November 2019 в 02:53
поделиться

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

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

18
ответ дан Mike Burton 23 November 2019 в 02:53
поделиться

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

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

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

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

И т.д.

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

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

14
ответ дан Wedge 23 November 2019 в 02:53
поделиться

Я забываю, где я получил это от, но:

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

16
ответ дан EBGreen 23 November 2019 в 02:53
поделиться

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

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

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

13
ответ дан Gulzar Nazim 23 November 2019 в 02:53
поделиться

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

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

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)

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

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

13
ответ дан Steven Huwig 23 November 2019 в 02:53
поделиться

В порядке:

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

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

9
ответ дан 2 revs 23 November 2019 в 02:53
поделиться

Для одного рассмотрите следующий отрывок:

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

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

6
ответ дан ddimitrov 23 November 2019 в 02:53
поделиться

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

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

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

3
ответ дан 2 revs 23 November 2019 в 02:53
поделиться

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

5
ответ дан Onorio Catenacci 23 November 2019 в 02:53
поделиться

Вы услышали о "ВЕБ-" проекте Donald Knuth реализовать его Грамотное программирование понятие? Это больше, чем самодокументирует код; это больше похоже на документацию, которая может быть скомпилирована и выполнена как код. Я не знаю, насколько это используется сегодня все же.

5
ответ дан catfood 23 November 2019 в 02:53
поделиться

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

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

4
ответ дан JaredPar 23 November 2019 в 02:53
поделиться

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

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

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

4
ответ дан 2 revs 23 November 2019 в 02:53
поделиться

Я удивлен, что никто не вызвал" Грамотное программирование ", техника, разработанная в 1981 Donald E. Knuth из TeX и "Искусства Программирования" известность.

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

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

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

, Если можно найти книгу Knuth по нему в библиотеке (Donald E. Knuth, Грамотное программирование, Стэнфорд, Калифорния: Центр Исследования Языка и информации, 1992, Примечания Лекции CSLI, № 27.) необходимо считать его.

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

4
ответ дан Quantenmechaniker 23 November 2019 в 02:53
поделиться

Мое представление записано в этом сообщении:

одна единственная подсказка для документирования кода.

Выборка:

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

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

4
ответ дан 2 revs, 2 users 71% 23 November 2019 в 02:53
поделиться

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

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

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

необходимо ли быть в состоянии считать то, что Вы пишете?

Исходный код не записан на естественном языке. Это попробовали (например, ФОРТРАН), но это не абсолютно успешно.

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

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

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

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

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

4
ответ дан Guge 23 November 2019 в 02:53
поделиться

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

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

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

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

3
ответ дан Ralph M. Rickenbach 23 November 2019 в 02:53
поделиться

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

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

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

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

3
ответ дан Uri 23 November 2019 в 02:53
поделиться

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

169
ответ дан andygeers 23 November 2019 в 02:53
поделиться

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

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.

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

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

376
ответ дан 8 revs, 3 users 82% 23 November 2019 в 02:53
поделиться

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

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

5
ответ дан 23 November 2019 в 02:53
поделиться

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

  • Вы должны задокументировать, «что» делает процедура.
  • Вы не должны задокументировать, «как» она это делает, если только особые случаи (например, обратитесь к статье с конкретным алгоритмом). Это должно быть подтверждено самими собой.
5
ответ дан 23 November 2019 в 02:53
поделиться
Другие вопросы по тегам:

Похожие вопросы: