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

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

• [ http://tomsdomain.com/aesop/id87.htm] [1]

//, если это не важная персона, не разъедайте об этом.

//, Если Вы пишете комментарии на всем протяжении, важные не будут замечены

• комментарии Параметра Метода: Должен умереть. Это - дублирование кода.

//Параметры должны быть очевидными.

• WTF-факторное воображение: Будет кто-то, включая меня, говорить WTF этому?

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

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

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

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

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

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

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

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

Я изменил бы к лучшему это.

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

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

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

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

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

я не говорю, "не комментирует неясный код". Я говорю, "ясно дают понять Ваш код".

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

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

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

, Хотя... Я действительно читал кавычку, однажды приписанную Bill Gates: "Код ЯВЛЯЕТСЯ документацией".

Пойди разберись.

Некоторые перспективы от лагеря некомментария.

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

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

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

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

Я всегда использую System.out для объяснения, что делает код. Тем путем можно распечатать его прочь и считать его дома: p

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

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

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

Очень смешанные исходные данные здесь это кажется:)

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

' 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, проблемно-ориентированный язык был создан. (И это - мое высеченное определение "описания".)

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

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

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

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

Сам документирующий код код, который это записано ясно с классом, методом, функцией и именами переменной, которые делают, это полно решимости и понятная функция. Если преуспели, это - документация.

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

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

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

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

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

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

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

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

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