Я обычно комментирую "ifs" и пишу на "человеческом языке", что это значит, например "проверяет, есть ли это A или B".
Я нахожу это лучше для младших программистов, которые читают код, чтобы сначала прочитать, что это значит, а затем проанализировать утверждение (также для меня, когда я проверяю старый код)
Чем вы занимаетесь? Как насчет других сценариев? Плюсы? Минусы?
Джефф имеет удивительный пост об этом предмете. Ссылки на сообщение и некоторые из реакции в блогах также заслуживают внимания.
Комментарии не должны быть "как" что-то сделано, а скорее "зачем" это сделано (за исключением ОЧЕНЬ редкого условия, когда то, что не очевидно от чтения кода, и я имею в виду, что это SUPER RARE).
Там трагический изъян с теорией "самодокументированного кода". Да, чтение кода скажет вам, что именно оно делает. Однако код не способен сообщить вам, что он должен делать.
Думаю, можно с уверенностью сказать, что все ошибки вызваны, когда код не делает то, что он должен делать:). Поэтому, если мы добавим некоторые ключевые комментарии, чтобы предоставить сопровождающим достаточно информации, чтобы знать, что должен делать кусок кода, мы дали им возможность исправить множество ошибок.
Это оставляет нам вопрос о том, сколько комментариев ввести. Если вы вкладываете слишком много комментариев, все становится утомительным для поддержания, и комментарии неизбежно будут устаревшими с кодом. Если вы вкладываете слишком мало, то они не особенно полезны.
Я нашел регулярные комментарии наиболее полезными в следующих местах:
1) Краткое описание в верхней части файла .h или .cpp для класса, объясняющего цель класса
2) Блок комментариев перед реализацией нетривиальной функции, объясняющей ее цель и детализирующий ее ожидаемые входы, потенциальные выходы и любые странности, которые следует ожидать при вызове функции.
Кроме этого, я склонен комментировать все, что может показаться кому-то непонятным или странным. Например: "Этот массив основан на 1 вместо 0 из-за бла-бла".
Я обычно комментирую "ifs" и пишу на "человеческом языке", что это значит, например "проверяет, есть ли это A или B".
Если вы это сделаете, может быть лучше реорганизовать так, чтобы сложная логическая логика была извлечена другим методом или, по крайней мере, представила переменную с именем, которая позволяет понять, что означает логика.
Проблема с комментариями заключается в том, что они (иногда) нарушают рекомендацию DRY (Do not Repeat Yourself). Когда вы дублируете логику, добавляя ее в документацию, даже комментарии рядом с кодом, вы рискуете потерять вещи. Вскоре комментарии могут стать неполными или неточными.
Тем не менее, я не против смотреть комментарии, даже если они немного устарели. Я столкнулся с кодом, который выглядит следующим образом:
// collect data
Data data = collectData();
// analyze data
Report report = analyze(data);
// print report
report.print();
Те типы комментариев абсолютно бесполезны для всех, и я обычно удалю их в поле зрения.
Я усвоил сложный способ кодирования самого низкого общего знаменателя. Это включает в себя множество действий.
блоки комментариев кода, не обязательно каждая строка. Объясните, почему следующий блок (или строфа) кода написан так, как он есть. Включите дату и ваши инициалы в комментарии, чтобы вы знали, когда был добавлен комментарий, и кто написал комментарий. Старайтесь избегать комментариев, таких как "это глупо" или "Я так чертовски блестяще", поскольку это действительно не помогает, и в будущем это может оказаться неверным. Если вы используете какие-либо причудливые трюки или делаете что-либо, что не очевидно из быстрого взгляда, объясните, что и почему.
использовать имена переменных для чтения. это означает, что нужно избегать однобуквенных переменных, таких как чума. гораздо проще угадать, что делает цикл, если индексная переменная называется rowIndex, чем i. Почти каждый цивилизованный язык имеет компилятор или интерпретатор, который будет вычищать имена переменных, прежде чем помещать вашу работу в машинный код, поэтому использование загадочных имен переменных никому не способствует.
помните, что компиляторы являются умными. Очень умно. Каждый современный компилятор знает, как оптимизировать циклы и другие основные вещи. Написание полного цикла while на одной строке может показаться вам причудливым, но оно скомбинирует то же самое и запустит других людей, просматривающих ваш код (и даже вы, если вы вернетесь к коду через несколько недель). Избегайте причудливых языковых трюков, если они делают код менее читаемым.
принять стиль и придерживаться его. Всегда делайте ifs, loop и т.д. В том же формате (и в том же отступе). Вы сможете легче определить различные функции вашего кода, так как одни и те же функции будут выглядеть одинаково. Если вы допустили ошибку, она будет выделяться немного больше.
Выполнение этих действий делает код более читаемым для всех. Принятие хороших привычек кодирования также снижает зависимость от комментариев, так что это двойной выигрыш.
Если раздел кода нуждается в комментариях. Вероятно, он нуждается в рефакторинге.
например.
void MyMethod()
{
//set the UI
myTextbox.text = "Foo";
myOthertextbox.text = "Bar";
foreach (n in thing)
//something other stuff
}
вероятно, необходимо реорганизовать, чтобы вывести материал UI.
void MyMethod()
{
SetUI();
foreach (n in thing)
//something other stuff
}
void SetUI()
{
myTextbox.text = "Foo";
myOthertextbox.text = "Bar";
}
Помимо описаний методов и свойств и т.д., я вообще не комментирую мой код, если только это немного сложно понять. Моя личная цель - написать код, который я смогу вернуться через год, и понять примерно через 5 минут, и я обычно достигаю этого. Лучший код достаточно прост, чтобы понять, что он не нуждается в комментариях.
Проблема с комментариями, чередующимися с кодом, заключается в том, что при изменении кода (код будет меняться) комментарии очень часто бывают или, по крайней мере, не последовательно. Это приводит к еще более запутанному, неподдающему себя безопасности коду, потому что после нескольких изменений комментарии и код не говорят почти то же самое.
Вместо этого я предпочитаю иметь комментарии для каждого модуля (класс, функция, что угодно). В этом разделе комментариев должно быть объяснено простым языком, для какой функции предназначен модуль.
Если я думаю, что часть кода достаточно сложна, чтобы гарантировать комментарий, я реорганизую ее в свою собственную функцию, поэтому имя функции и связанные комментарии могут объяснить, что она должна делать.
Идеально, код должен быть "самодокументированным", но, пожалуйста, игнорируйте тех, кто говорит "если код не является самодокументированным, вы его плохо написали". В реальном мире это не всегда возможно, в зависимости от сложности кода.
Очевидно, это не означает, что вы должны размещать комментарии повсюду или иметь такие вещи, как
option = option->next; // get the next option
i++; // increment i
но если фрагмент кода достаточно сложный, то есть комментарии, которые описывают то, что он должен делать, гораздо более ценны, чем необходимость в каком-то другом документе, надеющемся на будущее,
Я не комментирую очевидные вещи (например, "Установить я до 2" или "проверить, больше ли 5" ), но иногда просто небольшая информация о том, для чего используется код, т.е. "построить внешний таблица" или некоторые странности, такие как "MyClass.Count на самом деле Count-1". И, конечно, обходной путь для ошибок, т.е. "Обходное решение для KB123456 - URL-адрес на каком-то сайте, который объясняет ошибку..."
Итак, в основном: я почти никогда не комментирую "Что", но иногда "Почему".
Я понимаю это своего рода клише, но код должен сам документировать. Я склонен ошибаться на стороне объявления большего числа переменных для ясности (в предположении, что компилятор может/будет оптимизировать ненужные из них). Сохраняйте функции короткими, а переменные и функции хорошо обозначены. Я пытаюсь это сделать, а затем комментировать только сложные вещи.
Помните, однако, что более короткие функции затрудняют понимание того, как код в целом работает вместе. Имейте это в виду при регистрации функций (в отличие от отдельных строк кода). На уровне функции или даже единицы измерения вы должны документировать, как функции взаимодействуют друг с другом.
Попробуйте не комментировать код. Документируйте API, но старайтесь писать код, который не нужно комментировать, и это понятно из того, как называются переменные, функции и т.д. На это уже есть несколько хороших ответов. Конечно, когда вы делаете что-то эзотерическое или даже странное, а иногда вам нужно, вы должны поместить комментарий в код.
Но вот некоторые дополнительные материалы о том, как не комментировать.
Не помещайте дату создания/изменения ни в какие ваши комментарии. Информация о версии в заголовке в порядке, но не требуется, и, вероятно, не самая лучшая идея. Ваш VCS должен позаботиться об этом. Если вы не используете VCS для кода, который требует комментирования, вы делаете это неправильно. Научитесь использовать один (рекомендую git или Mercurial), пока он не станет вашей второй природой.
FIXME и evenmoreso TODO действительно не принадлежат коду, а также не в комментариях. Багтрекер - подходящее место для этого. Или, по крайней мере, TODO файл Toplevel.
Соблюдайте свои прозаические навыки. Всем известно, что вы машинист прикосновений, который может писать три страницы за такое же количество минут; но когда я читаю код, я читаю код и не предпочитаю комментариев, чтобы нарушить мое мышление.
Не пытайтесь объяснить архитектуру системы внутри комментариев. Даже документация по API не всегда является лучшим местом для этого. Если весь thig действительно сложный, используйте внешний, правильно отформатированный документ, который легче читать, желательно в формате pdf или html.
Просто помните: исходные файлы - это то, что делает код. Они не являются ни тем, как он это делает, ни почему они это делают. Как можно войти в документацию API (которую я не считаю "комментированием" в строгом смысле) и почему в документации по программе. Не путайте документацию с комментариями. Ваше руководство поблагодарит вас за это.
(Если вы подумывали о литературном программировании, это еще одна проблема, и у меня нет достаточного опыта, чтобы дать вам какие-либо советы здесь.)
Сам код должен быть способен объяснить , как он работает без комментариев. Комментарии, которые сопровождают код, должны объяснить , почему он работает.
Вы должны иметь возможность следить за кодом функции без комментариев и определять, что он делает, но без комментариев вы никогда не сможете понять, почему он делает то, что он делает. Хорошо написанные комментарии объясняют, как функция относится к большой картине, а также к некоторым из решений повседневного кодирования, которые были сделаны - причине для обертывания блока кода в условном выражении или с помощью try {} catch {} для кажущегося безобидного вида набора инструкций.
Пояснительные комментарии и использование хорошо названных переменных/методов/классов идут рука об руку. Вы не будете в полной мере осознавать это, пока не попадете в устаревшую систему, в которой не работал текущий сотрудник, и у которого есть нулевая документация.
В моей текущей работе я делаю комментарии, которые я еще не делал раньше - мы конвертируем VB6 в VB.NET, а два других программиста в компании мало или вообще не имеют опыта работы с истинным языком OO. Я делаю много комментариев как вещь типа учебного места на месте. Да, эта информация может быть во внешнем документе или даже в учебнике или он-лайн учебнике, но существует ТАК МНОГО! Я даю его в небольших дозах.
Я считаю это лучше для младших программистов...
Если вы серьезно сомневаетесь в ценности написания комментариев, тогда мне придется включить вас в группу "младших программистов".
Комментарии абсолютно важны.
Сложный код должен быть прокомментирован. Вы действительно верите, что весь написанный вами код интуитивно понятен всем, кто его прочитал?
Нет. Не думал. Прокомментируйте свой код.
Да. Я комментирую широко. Я занимаюсь забавными вещами на уровне, где OO необычен, операционная система - это мечта, а библиотеки - это миф.
Итак, когда я пишу драйверы для встроенной системы, я должен прокомментировать, чтобы сделать непрозрачный код, читаемый для моего маленького ума, читать на следующей неделе. Это также помогает, так как там большие куски кода, которые я не писал, и у меня нет документации, и поэтому я могу написать в комментариях, как разговаривать с этим кодом, где я делаю интерфейс с ним.
Итак, в то время как остальные из вас, гуру, могут быть настолько блестящими, что вы можете читать без комментариев С# - я недостаточно умен, чтобы читать мой раскованный код C. поэтому я комментирую, и мой код работает очень хорошо.: -)
Я документирую, что делает функция, ее параметры и то, что она возвращает и почему. Внутри функций я редко комментирую что-либо. Я нахожу, что если имена переменных выбраны хорошо, то это все необходимые комментарии.
В настоящее время я пишу в основном код С#, но считаю, что эта система работает практически для любого объектно-ориентированного языка, потому что функции в хорошо продуманном OO обычно не занимают более пятидесяти строк. Если они это сделают, я мог бы посыпать некоторые комментарии для документирования подразделов процесса, но в этот момент я обычно просто разбиваю одну функцию на подфункции.
Я пытаюсь прокомментировать только то, что необходимо. Как и какова цель этого класса, что делает этот метод (если не очевидный), какие значения могут иметь параметры и т.д. Я стараюсь избегать комментариев, описывающих, что делает код. Вместо этого я пытаюсь сделать код самоописательным. Извлеките более мелкие методы из больших кусков кода и т.д. Конечно, это не всегда возможно и может иногда даже ухудшать ситуацию. Вы должны найти баланс, где наиболее удобна комбинация кода и комментариев. Самое худшее, что вы можете сделать, это добавить комментарии к очевидным методам, таким как геттеры и сеттеры, когда они не делают больше, чем им нужно - получить или установить именованное поле. Одна вещь, которая действительно опасна для комментариев, заключается в том, что они могут устареть, когда изменения в реализации и комментарии будут забыты. Поэтому вы должны попытаться сосредоточиться на интересном материале, потому что то, что пользователи вашего кода или самого себя будут видеть и которым нужно доверять, если у них нет исходного кода;)
Я обычно просто комментирую в двух случаях.
Конечно, я всегда стараюсь дать свои переменные и функции значимым именам и минимизировать необходимость комментариев таким образом.
"Я не вижу код для всех комментариев", это выражение или подобное выражение, которое я слышал много раз в своей карьере. Это предупреждение, что слишком много комментариев слишком долго читают и замедляют производительность.
Итак, в общем, я ограничиваю свои комментарии комментариями. То есть я дам резюме класса и его намерения. Я дам краткое описание предложения для каждого метода/свойства, и я расскажу подробнее о сложной области кода. Я редко использую встроенные комментарии, потому что это отвлекает от потока и читаемости логики программы.
Чем дольше я программирую (yikes, я только что вступил в свое четвертое десятилетие), тем меньше комментариев я пишу. Я постоянно реорганизую свой код, чтобы сделать его более понятным, потому что это проще и безопаснее, чем писать комментарии, чтобы объяснить это.
Поэтому я считаю, что, когда я возвращаюсь и читаю старый код, комментарии, которые я написал, почти всегда стоит читать.
Единственное место, где я пишу комментарии, даже если код не требует пояснений, содержится в документации по методу, поэтому IntelliSense имеет что-то для отображения. Даже если эти комментарии могут быть не полезны в 100% случаев, это просто раздражает, если я нахожусь над вызовом метода, и ничего не появляется.
Я пытаюсь удалить перенос комментариев в отдельные функции, когда кажется, что функция становится большой.
Чтобы выглядеть крупнее, я использую большой размер шрифта, например, 14 или 15.
Я комментирую как услугу другим, и только когда код "сделан". Когда я работаю над своими собственными проектами, я редко беспокоюсь о том, что лучше добавлять функции и исправлять ошибки, чем писать что-то, что я, вероятно, никогда не прочитаю.
Интересно, что, читая код других людей, я очень часто удаляю или игнорирую комментарии и смотрю прямо на код. Я считаю, что во многих случаях это может быть более понятным для чтения, чем соответствующие комментарии.
Я считаю, что в начале процедур/методов/модулей вы документируете причину/намерение всей части кода. Хорошо включать комментарии об изменениях (кто, когда, почему/что). В самом коде должны быть прокомментированы те вещи, которые могут быть неясными или допущениями, которые сделаны.
Не выполняйте сравнения с жестко закодированными числами, используйте константы со значимыми именами.
Мне пришлось поддерживать код, который был реорганизован до одного и двух линейных методов с кажущимися значимыми именами, но в реальности должны были быть комментарии, чтобы дать более полную картину того, что происходит, и как методы, связанные с другими вещи, которые происходили.
Как @Брэд-Уилсон сказал, почему не так. Но я также использую TODO в моем коде, но для производства я стараюсь их ограничить.
Перейдите к главе 32 "Самодокументирующий код" вашей копии Code Complete.
Старая пословица, наставница, поделившаяся мной, хотя я не знаю исходного источника:
Хорошие программисты комментируют свой код.
Великие программисты говорят вам, почему была выбрана конкретная реализация.
Мастер-программисты расскажут вам, почему другие реализация не была выбрана.
Или слова на этот счет...
Одна вещь, которая должна быть более четко подчеркнута в этом обсуждении, - это различие между комментариями к коду и документацией API.
Поскольку современные генераторы документации работают путем анализа комментариев в коде (например, комментариев документации по XML в формате XML), некоторые разработчики могут мысленно комбинировать комментарии и документацию. Общее отношение к комментарию кода, показанного в этом потоке и в других местах, может заставить этих разработчиков не документировать свои API.
Хотя я согласен, что лучше всего сделать код чистым, а не комментировать, я также считаю важным документировать ваши интерфейсы. Документация также не должна быть слишком подробной. Он должен содержать только информацию, которая была бы ценна для человека, использующего интерфейс. Он не должен содержать лишних деталей реализации. Но информация, которая присутствует, должна быть полной, так что пользователь не должен когда-либо смотреть на ваш исходный код, чтобы использовать ваш модуль. Документация, которая появляется в подсказках вашего IDE или более длинном документе, который появляется в другом месте, должен быть всем, что необходимо.
Этот подход поощряет инкапсуляцию и, следовательно, хорошие методы программирования.
/// <summary>
/// Gets the name of a seventeenth century philosopher. The name is
/// chosen randomly among those that are stored in the database,
/// whose primary cultural contribution was published between 1601
/// and 1700. Names may be repeated on multiple calls. The
/// ConnectionString property must be set before calling this method.
/// </summary>
/// <exception cref="InvalidOperationException">The ConnectionString
/// property was not set.</exception>
/// <exception cref="SqlException">A problem occured with the database
/// connection.</exception>
public string GetRandomSeventeenthCenturyPhilosopherName()
{
...
Я часто дам штамп моих комментариев и описываю, ПОЧЕМУ я что-то делаю, а не как (в конце концов, как это делается в коде).
Если я вношу изменения, особенно если он управляется пользователем, я не буду удалять старый код, но прокомментирую его по причине его удаления. Это похоже на систему "на месте", за исключением того, что она позволяет мне читать историю всякий раз, когда я изменяю код.
-R