Я хочу услышать от вас любые советы и опыт написания комментариев в вашем коде. Как вы пишете их наиболее простым и информативным способом? Какие у вас привычки, комментируя части кода? Может быть, какие-то экзотические рекомендации?
Я надеюсь, что этот вопрос соберет самые интересные советы и рекомендации для комментариев, что-то полезное, что каждый может извлечь уроки.
Хорошо, я начну.
Обычно я не использую
/* */
комментарии, даже когда мне нужно комментировать много строк.Преимущества : код визуально выглядит лучше, чем когда вы смешиваете такой синтаксис с однострочными комментариями. Большинство IDE имеют возможность комментировать выделенный текст, и они обычно делают это с однострочным синтаксисом.
Недостатки : трудно редактировать такой код без IDE.
Поставьте «точку» в конце любого законченного комментария.
Например:
//Recognize wallpaper style. Here I wanted to add additional details int style = int.Parse(styleValue); //Apply style to image. Apply(style);
Преимущества : ставьте «точку» только в комментариях, которые вы закончили. Иногда вы можете написать временную информацию, поэтому отсутствие «точки» скажет вам, что вы хотите вернуться и добавить дополнительный текст к этому комментарию.
Выровняйте текст в перечислениях, комментируя параметры и т. Д.
Например:
public enum WallpaperStyle { Fill = 100, //WallpaperStyle = "10"; TileWallpaper = "0". SizeToFit = 60, //WallpaperStyle = "6"; TileWallpaper = "0". Stretch = 20, //WallpaperStyle = "2"; TileWallpaper = "0". Tile = 1, //WallpaperStyle = "0"; TileWallpaper = "1". Center = 0 //WallpaperStyle = "0"; TileWallpaper = "0". };
Преимущества : просто выглядит лучше и визуально легче найти то, что вам нужно.
Недостатки : тратить время на выравнивание и сложнее редактировать.
Введите текст комментария, который вы не можете получить, проанализировав код.
Например, глупый комментарий:
//Apply style. Apply(style);
Преимущества : у вас будет понятный и небольшой код с только полезной информацией в комментариях.
источник
:3,7 Align //
выравнивание комментариев в строках 3-7.Ответы:
Некоторые из приведенных ниже высказываний носят весьма личный характер, хотя и с некоторым оправданием, и предназначены именно для этого.
Типы комментариев
Для краткой версии ... Я использую комментарии для:
Читайте ниже для деталей и (возможно, неясных) причин.
Последние комментарии
В зависимости от языка, используются однострочные комментарии или многострочные комментарии. Почему это зависит? Это просто вопрос стандартизации. Когда я пишу код на C, я отдаю предпочтение старомодному коду ANSI C89 по умолчанию, поэтому я предпочитаю всегда иметь
/* comments */
.Поэтому я хотел бы иметь это в C большую часть времени, а иногда (в зависимости от стиля кодовой базы) для языков с C-подобным синтаксисом:
Emacs хорош и делает это для меня
M-;
.Если язык поддерживает однострочные комментарии и не основан на C, я буду более склонен использовать однострочные комментарии. В противном случае, я боюсь, что теперь взял эту привычку. Что не обязательно плохо, так как заставляет меня быть кратким.
Многострочные комментарии
Я не согласен с вашей заповедью, используя однострочные комментарии, так как это более привлекательно. Я использую это:
Или вот это (но я уже не так часто, за исключением личной базы кодов или в основном для уведомлений об авторских правах - это исторически для меня и происходит из моего образования. К сожалению, большинство IDE облажаются при использовании автоформатирования) :
Если это действительно необходимо, то я бы прокомментировал встроенное, используя то, что упомянул ранее для трейлинг-комментариев, если имеет смысл использовать его в трейлинг-позиции. На особом обратном случае, например, или к документу
switch
«scase
заявления (редко, я не часто использовать переключатель), или когда документ ветви вif ... else
потоке управления. Если это не один из них, то, как правило, блок комментария вне области действия, описывающий шаги функции / метода / блока, имеет больше смысла для меня.Я использую их исключительно в исключительных случаях, за исключением случаев, когда кодирование выполняется на языке без поддержки комментариев документации (см. Ниже); в этом случае они становятся более распространенными. Но в общем случае, это действительно просто для документирования вещей, которые предназначены для других разработчиков и являются внутренними комментариями, которые действительно должны выделяться. Например, чтобы документировать обязательный пустой блок, такой как «принудительный»
catch
блок:Что уже безобразно для меня, но я бы терпел в некоторых обстоятельствах.
Документация Комментарии
Javadoc & al.
Я бы обычно использовал их в методах и классах для документирования версий, представляющих функцию (или изменяющих ее), особенно если это для общедоступного API, и для предоставления некоторых примеров (с понятными случаями ввода и вывода и особыми случаями). Хотя в некоторых случаях для документирования их лучше было бы использовать единичный случай, юнит-тесты не обязательно читаются человеком (независимо от того, какую DSL-штуку вы используете).
Они немного меня раздражают, документируя поля / свойства, так как я предпочитаю завершающие комментарии для этого, и не все рамки генерации документации поддерживают конечные комментарии документации. Например, Doxygen, а JavaDoc - нет, а это значит, что вам нужен верхний комментарий для всех ваших полей. Я могу пережить это, хотя, поскольку строки Java в большинстве случаев относительно длинные, в любом случае, последний комментарий может меня выпугнуть, если расширить линию за пределы моего порога допуска. Если бы Javadoc когда-нибудь подумал об улучшении этого, я был бы намного счастливее.
Закомментированный код
Я использую однострочные только по одной причине, в языках, подобных C (за исключением случаев компиляции для строгого C, где я их на самом деле не использую): чтобы закомментировать материал при кодировании. Большинство IDE будут иметь переключатели для однострочных комментариев (с выравниванием по отступу или по столбцу 0), и это подходит для этого варианта использования для меня. Использование переключателя для многострочных комментариев (или выбор в середине строки для некоторых IDE) затруднит легкое переключение между комментариями / комментариями.
Но так как я против закомментированного кода в SCM, он обычно очень недолговечный, потому что я буду удалять закомментированные фрагменты перед фиксацией. (Прочтите мой ответ на этот вопрос на тему «отредактировано в комментариях и SCM» )
Стили комментариев
Я обычно пишу:
Заметка о грамотном программировании
Возможно, вы захотите заинтересоваться грамотным программированием , о котором рассказывает Дональд Кнут .
В качестве дополнительного примечания и примера: структура JavaScript underscore.js , несмотря на несоответствие моему стилю комментирования, является довольно хорошим примером хорошо кодированной базы документов и правильно сформированного аннотированного источника - хотя, возможно, не лучшим для использования в качестве ссылка на API).
Это личные условности. Да, я могу быть странным (и вы тоже). Это нормально, если вы соблюдаете и соблюдаете кодовые правила вашей команды при работе с коллегами или не подвергаете себя радикальной атаке их предпочтения и не сожительствуете . Это часть вашего стиля, и вы должны найти тонкую грань между разработкой стиля кодирования, который определяет вас как программиста (или как последователя школы мысли или организации, с которой у вас есть связь) и соблюдением соглашения группы о согласованности ,
источник
Когда я учился в университете, меня всегда учили комментировать каждую строку кода и каждый заголовок метода. Он был забит до такой степени, что вы сделали это без вопросов. Будучи частью нескольких команд разработки Agile в разных компаниях, я могу сказать, что могу написать комментарий один раз в синюю луну.
Причина этого двоякая: во-первых, нам больше не нужно писать длинные монолитные методы, которые выполняют 101 разную работу, имена классов, методов и переменных должны быть самодокументированы. Возьмите следующий метод входа в качестве примера.
Это может быть возвращено к чему-то, что является намного более читаемым и, возможно, повторно используемым:
Вы можете ясно видеть из метода входа в систему, что происходит. Это может показаться дополнительной работой, но ваши методы невелики и имеют только одну работу. Кроме того, имена методов носят описательный характер, поэтому нет необходимости писать комментарии к заголовку метода. Если у вас слишком много методов, это указывает на то, что связанные методы должны быть повторно преобразованы в другой объект, такой как UserAuthenticationService, помните, что объект должен иметь только одно задание.
Во-вторых, каждый отдельный фрагмент кода, который вы пишете, включая комментарии, должен быть сохранен, чем больше у вас комментариев, тем больше нужно поддерживать. Если вы переименуете класс или переменную, вы получите ошибку компиляции, но если вы измените способ работы раздела кода или удалите его и не обновляете какие-либо связанные комментарии, то ошибки компиляции не будет, и комментарии будут зависать, вызывая путаницу ,
Если вы пишете API, то я считаю, что любые открытые интерфейсы, классы, перечисления должны иметь хорошо написанные комментарии заголовков для документации.
источник
Сосредоточьтесь меньше на формате и больше на содержании. Например, комментарии в вашем примере не говорят мне ничего нового. Они хуже, чем бесполезные, так как они отвлекают от чтения кода, и такие комментарии, в лучшем случае, являются неопределенной ссылкой на то, что, по мнению первоначального программиста, он делал во время написания. Я могу видеть из примера кода, что вы применяете стиль «apply (Style)», я могу читать исходные тексты. Я не могу читать ваши мысли, - почему вы это делаете, это то, что комментарий должен сказать мне. например, а не
//Apply style.
Apply(style);
должно быть
// Unlike the others, this image needs to be drawn in the user-requested style apply(style);
Большинство из нас работают в командах над существующим кодом, форматируют так, как это делает остальная команда, так, как это уже делается. Согласованность гораздо важнее, чем красивая.
источник
Насколько это возможно, напишите свой код так, чтобы комментарии были совершенно посторонними. Добавляйте комментарии только тогда, когда код не может быть написан таким образом, чтобы сделать очевидной важную концепцию.
источник
Я предпочитаю, чтобы все было просто. Я избегаю всех видов модного форматирования. Основная причина этого заключается в том, что я считаю, что исходный код должен быть легко редактируемым даже в самом простом текстовом редакторе. Я также никогда не делаю жесткие переносы абзацев текста, а вместо этого позволяю редактору делать мягкие переносы (без добавления новых строк).
источник
Я часто вижу подобные комментарии, и некоторые инструменты автоматически генерируют их таким образом:
На две строки меньше:
Среды IDE и редакторы, находящиеся чуть выше уровня блокнота, могут обнаруживать комментарии и печатать их другим цветом. Нет необходимости украшать начало строки звездочками.
Вы даже сэкономите несколько байтов, если используете отступ для отступа.
Если вы не используете сложный редактор, который отображает комментарий серым тоном, большое количество звездочек будет работать как акцент и привлекать ваше внимание, что является противоположностью правильной вещи: оставаться позади.
источник
Вот «анти-паттерн», который я нашел в коде моей работы: использование комментариев в качестве «журнала изменений»; для этого нужен журнал в вашей системе контроля версий. Код полон таких вещей, как:
и обычно часто включает в себя старый код, который был закомментирован (опять же, в этом суть системы VCS, поэтому нет необходимости быть в коде после написания нового кода). Также следует избегать повторяющихся комментариев типа «Зачем нам это нужно?» или, что еще хуже, «Это, вероятно, должно быть переименовано» (потому что существуют сложные инструменты для переименования, поэтому за то время, которое понадобилось вам, чтобы написать этот комментарий, вы могли бы переименовать объект). Опять же, я имею дело с обоими этими комментариями на регулярной основе, в соответствии с:
источник
источник
Читатели кода обычно пытаются ответить на три вопроса:
Все остальное должно быть выражено в коде. Как и проза, это искусство и требует много практики. Единственный способ узнать, понятен ли ваш код, - это заставить кого-то прочесть его. Когда они что-то не понимают, не объясняйте это устно. Улучшите код. Добавьте комментарии в качестве последнего средства.
Если я увижу «двойную длину», я спрошу: «Какая единица измерения?» Не добавляйте комментарий. Измените имя переменной. Если я вижу блок кода и говорю «что это делает?», Не добавляйте комментарий. Извлеките функцию со значимым именем. Если вы не можете извлечь функцию, потому что для этого потребуется 17 аргументов, выполните рефакторинг кода.
источник