Каков Ваш индивидуальный подход/, берут комментарий?

Мы добавляем комментарии, которые предоставляют справочную документацию API для всех общедоступных классов / методы / свойства / и т.д... Это определенно стоит усилия, потому что Документация XML в C# имеет хороший эффект обеспечения IntelliSense пользователям этих общедоступных API..NET 4.0's контракты кода позволит нам улучшиться далее относительно этой практики.

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

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

Я комментирую так же по мере необходимости - затем, так же, как мне будет нужен он год спустя.

Вот мое представление (на основе нескольких лет диссертации):

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

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

Теперь, функциональные комментарии являются действительно проблемой, и до некоторой степени Ваш друг прав, что для большей части кода нет никакого экономичного стимула для полных спецификаций способа, которым документируются популярные API. Важная вещь здесь состоит в том, чтобы определить то, что является "директивами": директивы являются теми информационными частями, которые непосредственно влияют на клиенты и требуют некоторого прямого действия (и часто неожиданны). Например, X должен быть вызван прежде Y, не называйте это снаружи потока UI, знайте, что это имеет определенный побочный эффект и т.д. Это вещи, которые действительно важны для получения.

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

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

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

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

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

кроме того, если я делаю что-то конкретный путь, который не выглядит правильным на первый взгляд, но я знаю, что это - потому что рассматриваемый код является обходным решением для платформы или чего-то как этот, затем я прокомментирую с комментарием ПРЕДУПРЕЖДЕНИЯ.

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

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

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

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

Так в этом комментарии экземпляра чувствует себя подобно излишеству:

/*
 * this function adds two integers
 */
int add(int x, int y)
{
    // add x to y and return it
    return x + y;
}

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

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

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

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

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

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

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

я не забываю изучать C# и читать чужой код, как который я часто расстраивался вопросами, "какое из 9 значений символа двоеточия делает этот одно среднее?" Если Вы не знаете название функции, как Вы ищете его?! (Примечание стороны: Это было бы хорошей функцией IDE: Я выбираю оператор или другой маркер в коде, щелчок правой кнопкой затем показывает мне, это - часть языка и имя функции. C# нужно это, VB меньше.)

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

И мне нравятся @17 из комментария 26 (добавленный акцент):

... чтение кода скажет Вам точно, что это выполнение. Однако код неспособен к сообщению Вам, что это , предположил делать.

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

В целом, при программировании Вас должен сделать вещи однажды в одном месте только.

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

Однако, если дальнейшее объяснение необходимо, я добавлю комментарий, снабженный префиксом ИНФОРМАЦИЮ, ОТМЕТИТЬ, и подобный...
ИНФОРМАЦИЯ: комментарий для получения общей информации, если кто-то незнаком с этой областью.
ПРИМЕЧАНИЕ А: комментарий к предупреждению потенциальной причуды, такой как странное бизнес-правило / реализация.
, Если я конкретно не хочу людей, касающихся кода, я мог бы добавить ПРЕДУПРЕЖДЕНИЕ: или подобный префикс.

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

Подавляющее большинство моего commnets на уровне класса и уровне метода, и мне нравится описывать высокоуровневое представление вместо просто args/return значение. Я особенно стараюсь описать любую "нелинейность" в функции (пределы, угловые случаи, и т.д.), который мог сбить с толку неосторожное.

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

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

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

комментарии Требования и "измерение производительности" в строках кода могут вести для выбрасывания, такие как:

/*****
 *
 * Increase the value of variable i,
 * but only up to the value of variable j.
 *
 *****/

if (i < j) {
    ++i;
} else {
    i = j;
}

, а не сжатое (и ясный соответственно квалифицированному программисту):

i = Math.min(j, i + 1);

YMMV

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

РЕДАКТИРОВАНИЕ: Это звучало немного напыщенным, но я думаю, что слишком много людей забывают, что даже названия переменных или структуры, которые мы используем в коде, все просто "отмечают" - у них только есть значение нам, потому что наши мозги видят строку символов такой как customerNumber и понимают, что это - клиентское число. И в то время как это верно, что комментарии испытывают недостаток в любом "осуществлении" компилятором, они до сих пор не удалены. Они предназначены, чтобы передать значение другому человеку, программисту - человеку, который читает текст программы.

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

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

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

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

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

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

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

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

strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

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

//when under attack, sidestep and retaliate with rocket bundles
strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

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

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

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

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

Документируют контракт каждой функции и, для каждого типа объекта, что это представляет и любые ограничения на допустимое представление (технически, функция абстракции и инвариант представления ). Используйте исполняемый файл, тестируемая документация, где практичный (doctests, модульные тесты, утверждения), но также и пишут короткие комментарии, дающие суть, где полезный. (Где тесты принимают форму примеров, они являются неполными; где они - полные, точные контракты, они могут быть такой же работы к grok как сам код.) Пишут комментарии верхнего уровня для каждого модуля и каждого проекта; они могут объяснить конвенции, которые сохраняют все Ваши другие комментарии (и код) короткий. (Это поддержки именование поскольку документация: с конвенциями, установленными, и место, мы можем ожидать находить тонкость отмеченной, мы можем быть уверены чаще, что имена говорят всему, что мы должны знать.) Дольше, стилизованный, раздраженно избыточные Javadocs имеют свое использование, но помогли генерировать обратную реакцию.

(Например, это:

Выполняют n-сгиб frobulation.
@param n количество раз к frobulate
@param x x-координата центра frobulation
@param y y-координата центра frobulation
@param z z-координата центра frobulation

могла быть похожей "на Frobulate n времена вокруг центра (x, y, z)". Комментарии не должны быть тяжелой работой, чтобы читать и записать.)

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

Назад на заявлении, что мы документируем ради локального понимания: что делает эта функция?

def is_even(n): return is_odd(n-1)

Тесты, если целое число ровно? Если is_odd() тесты, если целое число нечетно, то да, который работает. Предположим, что у нас было это:

def is_odd(n): return is_even(n-1)

то же обоснование говорит это is_odd() тесты, если целое число нечетно. Соедините их, конечно, и никакой работы, даже при том, что каждый работает, если другой делает. Измените его немного, и у нас был бы код, который действительно работает, но только для натуральных чисел, в то время как все еще локально быть сходством с это работает на целые числа. В микромире это - то, на что похоже понимание кодовой базы: трассировка зависимостей вокруг в кругах, чтобы попытаться перепроектировать предположения, которые автор, возможно, объяснил в строке или два, если бы они обеспокоились. Я ненависть расход духа беспечные кодеры поместил меня в этот путь по нескольким прошлых десятилетий: о, этот метод похож на него, имеет побочный эффект farbuttling warpcore... всегда? Ну, если нечетный crobuncles desaturate, по крайней мере; они? Лучше проверьте весь код crobuncle-обработки..., который поставит его собственные проблемы к пониманию. Хорошая документация сокращает этот O (n) преследование указателя вниз к O (1): например, знание контракта функции и контрактов вещей, которые это явно использует, код функции, должно иметь смысл без дальнейшего знания системы. (Здесь, контракты, говоря is_even() и is_odd() работа над натуральными числами сказала бы нам, что обе функции должны протестировать на n==0.)

Мне всегда нравилось , Рефакторинг берет комментарий:

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

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

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

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

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

Мой подход:

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

Я ДЕЙСТВИТЕЛЬНО отвергаю код, который не соблюдает это правило в самом строгом смысле.

Использование хорошо отформатированного XML - комментарии очевидны.

Неряшливые комментарии - это небрежный код!