Каковы Ваши “твердые правила” о комментарии Вашего кода?

По-моему, TODO/TBD/FIXME и т.д. в порядке, чтобы иметь в коде, который в настоящее время работается на, но когда Вы видите код, который не был затронут за 5 лет и полон их, Вы понимаете, что это - довольно паршивый способ удостовериться, что вещи починены. Короче говоря, примечания TODO в комментариях имеют тенденцию оставаться там. Лучше для использования bugtracker, если у Вас есть вещи, которые должны быть починены в какой-то момент.

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

Мое любимое эмпирическое правило относительно комментариев: если код и комментарии не соглашаются, то оба являются, вероятно, неправильными

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

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

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

Директивы, любой "делает" или "не делают" инструкций, которые влияют на клиент: не звоните от потока UI, не используйте в производительности критический код, назовите X прежде Y, выпустите возвращаемое значение после использования и т.д.

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

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

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

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

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

Я подписываю свой код.

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

P.S. То, что Вы используете кавычки вокруг "твердых правил", говорит. Правила, которые не осуществляются, не являются "твердыми правилами" и единственными правилами, которые осуществляются, находятся в коде.

Я создаю блок комментария в начале своего кода, перечисляя цель программы, дата, это было создано, любая информация о лицензии/авторском праве (как GPL), и история версий.

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

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

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

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

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

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

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

Я фокусируюсь на почему. Поскольку, какой часто легок читаемый. TODO's является также большим, они экономят много времени.

И я документирую интерфейсы (например, форматы файлов).

Я документирую каждый класс, каждую функцию, каждую переменную в классе. Простые DocBlocks являются путем вперед.

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

Например, первый раздел одного из моих классов PHP

/**
 * Class to clean variables
 *
 * @package     Majyk
 * @author      Martin Meredith <martin@sourceguru.net>
 * @licence     GPL (v2 or later)
 * @copyright   Copyright (c) 2008 Martin Meredith <martin@sourceguru.net>
 * @version     0.1
 */
class Majyk_Filter
{
    /**
     * Class Constants for Cleaning Types
     */
    const Integer            = 1;
    const PositiveInteger    = 2;
    const String             = 3;
    const NoHTML             = 4;
    const DBEscapeString     = 5;
    const NotNegativeInteger = 6;

    /**
     * Do the cleaning
     *
     * @param   integer Type of Cleaning (as defined by constants)
     * @param   mixed   Value to be cleaned
     *
     * @return  mixed   Cleaned Variable
     *
     */

Но затем, я буду также иногда документировать значительный код (от моего init.php

// Register the Auto-Loader
spl_autoload_register("majyk_autoload");

// Add an Exception Handler.
set_exception_handler(array('Majyk_ExceptionHandler', 'handle_exception'));

// Turn Errors into Exceptions
set_error_handler(array('Majyk_ExceptionHandler', 'error_to_exception'), E_ALL);

// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");  

И, если это не будет сам объяснительное, почему что-то делает что-то определенным способом, я прокомментирую это

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

Инструкции я следую:

Комментарии 1/говорят то, что делается, код говорит, как он делается - не копируют Ваше усилие.

Комментарии 2/должны обратиться к блокам кода, не каждой строке. Это включает комментарии, которые объясняют целые файлы, целые функции или просто сложный отрывок кода.

3/, Если я думаю, что возвратился через год и не понимаю комбинацию кода/комментария затем мои комментарии, еще не достаточно хороши.

Я записал полный текст статьи о плохих комментариях. Наслаждаться :)

Как плохие комментарии рождаются в Вашем коде

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

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

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

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

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

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

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

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

Если комментарий устарел (не соответствует коду), удалите его или обновите его. Никогда не оставляйте неточный комментарий на месте.

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

1. Я комментирую общественность или защищенные функции с метакомментариями, и обычно поражаю закрытые функции, если я помню.
2. Я комментирую, почему любой блок достаточно сложного кода существует (личный выбор). Почему важная часть.
3. Я комментирую, пишу ли я код, что я думаю, не оптимально, но я оставляю его внутри, потому что я не могу выяснить более умный путь, или я знаю, что буду осуществлять рефакторинг позже.
4. Я комментирую для напоминания мне или другим недостающей функциональности или предстоящего кода требований, не существующего в коде (TODO, и т.д.).
5. Я комментирую для объяснения сложных бизнес-правил, связанных с классом или блоком кода. Я, как было известно, записал несколько абзацев, чтобы удостовериться, что следующий парень/галлон знает, почему я записал сто классов строки.

Документация похожа на пол; когда это хорошо, очень, очень хорошо, и когда это плохо, это лучше чем ничего

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

Только проведите то время, занимаясь расследованиями однажды.

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