Каковы ваши "жесткие правила" комментирования вашего кода?
Я видел другие вопросы, но я все еще не удовлетворен тем, как эта тема освещена.
Я хотел бы извлечь перегнанный список вещей, чтобы проверить комментарии при проверке кода.
Я уверен, что люди будут говорить вещи, которые просто отменят друг друга. Но, может быть, мы сможем составить список для каждого лагеря. Для тех, кто вообще не комментирует, список будет очень коротким:)
22 ответа
У меня есть одно простое правило о комментировании: ваш код должен рассказывать историю того, что вы делаете; Ваши комментарии должны рассказать о том, почему вы это делаете.
Таким образом, я уверен, что тот, кто унаследует мой код, сможет понять смысл этого кода.
- Я комментирую публичные или защищенные функции с помощью мета-комментариев, и обычно, если я помню, поражаю приватные функции
- Я комментирую, почему существует любой достаточно сложный кодовый блок (суждение). Почему это важная часть.
- Я комментирую, если я пишу код, который я считаю неоптимальным, но я оставляю его, потому что я не могу найти более разумный способ, или я знаю, что буду рефакторинг позже.
- Я комментирую, чтобы напомнить себе или другим о недостающей функциональности или готовящемся коде требований, отсутствующем в коде (TODO и т. Д.).
- Я комментирую, чтобы объяснить сложные бизнес-правила, связанные с классом или частью кода. Мне известно, что я написал несколько абзацев, чтобы убедиться, что следующий парень / гал знает, почему я написал класс из ста строк.
Если комментарий устарел (не соответствует коду), удалите его или обновите. Никогда не оставляйте неточный комментарий на месте.
Пишите читаемый код, который говорит сам за себя, насколько это возможно. Добавляйте комментарии всякий раз, когда вам нужно написать код, который слишком сложен для понимания с первого взгляда. Также добавьте комментарии, чтобы описать бизнес-цель, стоящую за кодом, который вы пишете, чтобы упростить его поддержку / рефакторинг в будущем.
Документация похожа на секс; когда это хорошо, это очень, очень хорошо, а когда это плохо, это лучше, чем ничего
Комментарии, которые вы пишете, могут показывать качество вашего кода. Бесчисленное количество раз я удалял комментарии в своем коде, чтобы заменить их более качественным и понятным кодом. Для этого я следую нескольким правилам антикомментирования:
- Если ваш комментарий просто объясняет строку кода, вы должны либо позволить этой строке кода говорить за себя, либо разбить ее на более простые компоненты.
- Если ваш комментарий объясняет блок кода внутри функции, вам, вероятно, следует объяснить новую функцию.
Это действительно одно и то же правило, повторяемое для двух разных контекстов.
Другие, более нормальные правила, которым я следую:
- При использовании динамически типизированного языка документируйте ожидания, которые важные функции делают в отношении своих аргументов, а также ожидания, которые могут вызывать вызывающие стороны в отношении возвращаемых значений. Важными функциями являются те, которые когда-либо будут иметь нелокальных абонентов.
- Когда ваша логика продиктована поведением другого компонента, хорошо задокументировать, каково ваше понимание и ожидания этого компонента.
При реализации RFC или другой спецификации протокола, прокомментируйте конечные автоматы / обработчики событий / и т. Д. С разделом спецификации, которому они соответствуют. Не забудьте указать версию или дату спецификации, на случай, если она будет пересмотрена позже.
Не существует жестких правил - жесткие правила ведут к догме, и люди обычно следуют догме, когда они недостаточно умны, чтобы думать самостоятельно.
Правила, которым я следую:
1 / Комментарии говорят о том, что делается, код говорит о том, как это делается - не дублируйте свои усилия.
2 / Комментарии должны относиться к блокам кода, а не к каждой строке. Это включает в себя комментарии, которые объясняют целые файлы, целые функции или просто сложный фрагмент кода.
3 / Если я думаю, что вернусь через год и не пойму комбинацию код / комментарий, мои комментарии еще недостаточно хороши.
Я обычно комментирую метод, прежде чем написать его. Я напишу строку или два комментария для каждого шага, который мне нужно сделать в функции, а затем я напишу код между комментариями. Когда я закончу, код уже прокомментирован.
Самое замечательное в этом то, что он комментируется до того, как я напишу код, поэтому в комментариях нет необоснованных предположений о предыдущих знаниях; Я сам ничего не знал о своем коде, когда писал их. Это означает, что их, как правило, легко понять, как и должно быть.
Я написал полную статью о плохих комментариях. Наслаждаться:)
Отличное правило для комментариев: если вы читаете код, пытаясь что-то выяснить, и комментарий где-то дал бы вам ответ, поместите его там, когда вы знаете ответ.
Только проведите это время, расследуя один раз.
Со временем вы будете знать, когда будете писать места, которые вам нужны, чтобы оставить руководство, и места, которые достаточно очевидны, чтобы оставаться в одиночестве. До тех пор вы будете тратить время на просмотр своего кода, пытаясь понять, почему вы что-то сделали:)
Я документирую каждый класс, каждую функцию, каждую переменную в классе. Простые 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");
И, если это не говорит само за себя, почему что-то делает определенным образом, я прокомментирую, что
Я сосредоточен на том, почему. Потому что то, что часто легко читается. TODO также хороши, они экономят много времени.
И я документирую интерфейсы (например, форматы файлов).
Я создаю блок комментария в начале своего кода, перечисляя назначение программы, дату ее создания, информацию о лицензии / авторских правах (например, GPL) и историю версий.
Я часто комментирую свои операции импорта, если неясно, почему они импортируются, особенно если программа в целом не нуждается в импорте.
Я добавляю строку документации в каждый класс, метод или функцию, описывающую, какова цель этого блока, и любую дополнительную информацию, которую я считаю необходимой.
У меня обычно есть разделительная линия для связанных разделов, например, создание виджетов, переменных и т. Д. Поскольку я использую SPE для своей среды программирования, она автоматически выделяет эти разделы, делая навигацию проще.
Я добавляю комментарии TODO в качестве напоминаний, пока я пишу код. Это хороший способ напомнить себе о необходимости рефакторинга кода после проверки его правильной работы.
Наконец, я комментирую отдельные строки, которые могут нуждаться в некотором пояснении или иным образом требовать метаданных для себя в будущем или для других программистов.
Лично я ненавижу смотреть на код и пытаться понять, что он должен делать. Если бы кто-то мог просто написать простое предложение, чтобы объяснить это, жизнь стала проще. Самодокументируемый код - это неправильное название в моей книге.
Единственное гарантированное место, где я оставляю комментарии: разделы TODO. Лучшее место для отслеживания вещей, которые требуют доработки - прямо в коде.
Действительно важно проверить, когда вы проверяете документацию заголовка (или как бы вы ни вызывали блок, предшествующий объявлению метода), это то, что директивы и предостережения легко обнаружить.
Директивы - это любые инструкции "делай" или "не делай", которые влияют на клиента: не вызывайте из потока пользовательского интерфейса, не используйте в коде, критичном к производительности, вызывайте X до Y, возвращайте возвращаемое значение после использования и т. Д.
Предостережения - это все, что может быть неприятным сюрпризом: оставшиеся элементы действий, известные предположения и ограничения и т. Д.
Когда вы сосредоточитесь на методе, который вы пишете и проверяете, вы увидите все. Когда программист использует ваш метод и тридцать других в час, вы не можете рассчитывать на тщательное чтение. Я могу выслать вам данные исследований, если вам интересно.
Я пишу статью на Medium, в которой я представлю это правило: когда вы фиксируете изменения в репозитории, каждый комментарий должен быть одного из этих трех типов:
- Заголовок лицензии вверху
- Комментарий к документации (например, Javadoc) или
- Комментарий.
Последний тип не должен быть постоянным. Либо дело сделано, и комментарий удален, либо мы решаем, что задача не нужна и
TODO комментарий удаляется.
Когда вы пишете комментарии, остановитесь, задумайтесь и спросите себя, можете ли вы изменить код, чтобы комментарии не были нужны. Можете ли вы изменить некоторые имена переменных, классов или методов, чтобы прояснить ситуацию? Будут ли некоторые asserts или другие проверки ошибок кодифицируют ваши намерения или ожидания? Не могли бы вы разделить несколько длинных участков кода на методы или функции с четкими именами? Комментарии часто являются отражением нашей неспособности написать (а-хем, код) ясно. Нелегко писать на компьютерных языках не всегда просто, но на это нужно время, потому что код никогда не лжет.
PS Тот факт, что вы используете кавычки вокруг "жестких правил", говорит о многом. Правила, которые не применяются, не являются "жесткими правилами", и единственные правила, которые применяются, находятся в коде.
Только pre-ambles; указать единую ответственность класса, любые примечания или комментарии и журнал изменений. Что касается методов, если какой-либо метод нуждается в существенном комментировании, пришло время провести рефакторинг.
На мой взгляд, TODO/TBD/FIXME и т. Д. Можно использовать в коде, над которым в настоящее время ведется работа, но когда вы видите код, который не был изменен в течение 5 лет и полон их, вы понимаете, что это довольно паршивый способ убедиться, что все исправлено. Короче говоря, заметки TODO в комментариях, как правило, остаются там. Лучше использовать багтрекер, если у вас есть вещи, которые нужно исправить в какой-то момент.
Hudson (CI-сервер) имеет отличный плагин, который сканирует TODO и отмечает, сколько их в вашем коде. Вы даже можете установить пороговые значения, при которых сборка будет классифицироваться как нестабильная, если их слишком много.
Мое любимое эмпирическое правило в отношении комментариев: если код и комментарии не совпадают, то оба они, вероятно, неверны
Мы написали статью о комментариях (на самом деле я сделал несколько) здесь: http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html
Это действительно просто: комментарии написаны, чтобы сказать вам, что код не может.
Это приводит к простому процессу: - Сначала напишите любой комментарий, который вы хотите. - Улучшите код, чтобы комментарий стал избыточным. - Удалите теперь избыточный комментарий. - Только коммит код, который не имеет лишних комментариев
Я добавляю 1 комментарий к блоку кода, который обобщает то, что я делаю. Это помогает людям, которые ищут определенную функциональность или раздел кода.
Я комментирую любой сложный алгоритм или процесс, который невозможно понять с первого взгляда.
Я подписываю свой код