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

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

Хорошо, я начну.

1. Обычно я не использую /* */комментарии, даже когда мне нужно комментировать много строк.

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

   Недостатки : трудно редактировать такой код без IDE.

2. Поставьте «точку» в конце любого законченного комментария.

   Например:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Преимущества : ставьте «точку» только в комментариях, которые вы закончили. Иногда вы можете написать временную информацию, поэтому отсутствие «точки» скажет вам, что вы хотите вернуться и добавить дополнительный текст к этому комментарию.

3. Выровняйте текст в перечислениях, комментируя параметры и т. Д.

   Например:

   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".
   };
   

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

   Недостатки : тратить время на выравнивание и сложнее редактировать.

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

   Например, глупый комментарий:

   //Apply style.
   Apply(style);
   

   Преимущества : у вас будет понятный и небольшой код с только полезной информацией в комментариях.

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

Типы комментариев

Для краткой версии ... Я использую комментарии для:

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

Читайте ниже для деталей и (возможно, неясных) причин.

Последние комментарии

В зависимости от языка, используются однострочные комментарии или многострочные комментарии. Почему это зависит? Это просто вопрос стандартизации. Когда я пишу код на C, я отдаю предпочтение старомодному коду ANSI C89 по умолчанию, поэтому я предпочитаю всегда иметь /* comments */.

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

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs хорош и делает это для меня M-;.

Если язык поддерживает однострочные комментарии и не основан на C, я буду более склонен использовать однострочные комментарии. В противном случае, я боюсь, что теперь взял эту привычку. Что не обязательно плохо, так как заставляет меня быть кратким.

Многострочные комментарии

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

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

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

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Если это действительно необходимо, то я бы прокомментировал встроенное, используя то, что упомянул ранее для трейлинг-комментариев, если имеет смысл использовать его в трейлинг-позиции. На особом обратном случае, например, или к документу switch«s caseзаявления (редко, я не часто использовать переключатель), или когда документ ветви в if ... elseпотоке управления. Если это не один из них, то, как правило, блок комментария вне области действия, описывающий шаги функции / метода / блока, имеет больше смысла для меня.

Я использую их исключительно в исключительных случаях, за исключением случаев, когда кодирование выполняется на языке без поддержки комментариев документации (см. Ниже); в этом случае они становятся более распространенными. Но в общем случае, это действительно просто для документирования вещей, которые предназначены для других разработчиков и являются внутренними комментариями, которые действительно должны выделяться. Например, чтобы документировать обязательный пустой блок, такой как «принудительный» catchблок:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Что уже безобразно для меня, но я бы терпел в некоторых обстоятельствах.

Документация Комментарии

Javadoc & al.

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

Они немного меня раздражают, документируя поля / свойства, так как я предпочитаю завершающие комментарии для этого, и не все рамки генерации документации поддерживают конечные комментарии документации. Например, Doxygen, а JavaDoc - нет, а это значит, что вам нужен верхний комментарий для всех ваших полей. Я могу пережить это, хотя, поскольку строки Java в большинстве случаев относительно длинные, в любом случае, последний комментарий может меня выпугнуть, если расширить линию за пределы моего порога допуска. Если бы Javadoc когда-нибудь подумал об улучшении этого, я был бы намного счастливее.

Закомментированный код

Я использую однострочные только по одной причине, в языках, подобных C (за исключением случаев компиляции для строгого C, где я их на самом деле не использую): чтобы закомментировать материал при кодировании. Большинство IDE будут иметь переключатели для однострочных комментариев (с выравниванием по отступу или по столбцу 0), и это подходит для этого варианта использования для меня. Использование переключателя для многострочных комментариев (или выбор в середине строки для некоторых IDE) затруднит легкое переключение между комментариями / комментариями.

Но так как я против закомментированного кода в SCM, он обычно очень недолговечный, потому что я буду удалять закомментированные фрагменты перед фиксацией. (Прочтите мой ответ на этот вопрос на тему «отредактировано в комментариях и SCM» )

Стили комментариев

Я обычно пишу:

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

Заметка о грамотном программировании

Возможно, вы захотите заинтересоваться грамотным программированием , о котором рассказывает Дональд Кнут .

Парадигма грамотного программирования [...] представляет собой отход от написания программ в порядке и порядке, наложенных компьютером, и вместо этого позволяет программистам разрабатывать программы в порядке, требуемом логикой и потоком их мыслей. 2 Грамотные программы написаны как непрерывное изложение логики на обычном человеческом языке, очень похожем на текст эссе [...].

Инструменты грамотного программирования используются для получения двух представлений из грамотного исходного файла: одно подходит для дальнейшей компиляции или выполнения компьютером, «запутанный» код, а другое - для просмотра в виде отформатированной документации, которая называется «сотканной» из грамотный источник.

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

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

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

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

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

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

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

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

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

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

Сосредоточьтесь меньше на формате и больше на содержании. Например, комментарии в вашем примере не говорят мне ничего нового. Они хуже, чем бесполезные, так как они отвлекают от чтения кода, и такие комментарии, в лучшем случае, являются неопределенной ссылкой на то, что, по мнению первоначального программиста, он делал во время написания. Я могу видеть из примера кода, что вы применяете стиль «apply (Style)», я могу читать исходные тексты. Я не могу читать ваши мысли, - почему вы это делаете, это то, что комментарий должен сказать мне. например, а не

//Apply style.

Apply(style);

должно быть

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

Большинство из нас работают в командах над существующим кодом, форматируют так, как это делает остальная команда, так, как это уже делается. Согласованность гораздо важнее, чем красивая.

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

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

Я часто вижу подобные комментарии, и некоторые инструменты автоматически генерируют их таким образом:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

На две строки меньше:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

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

Вы даже сэкономите несколько байтов, если используете отступ для отступа.

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

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

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

и обычно часто включает в себя старый код, который был закомментирован (опять же, в этом суть системы VCS, поэтому нет необходимости быть в коде после написания нового кода). Также следует избегать повторяющихся комментариев типа «Зачем нам это нужно?» или, что еще хуже, «Это, вероятно, должно быть переименовано» (потому что существуют сложные инструменты для переименования, поэтому за то время, которое понадобилось вам, чтобы написать этот комментарий, вы могли бы переименовать объект). Опять же, я имею дело с обоими этими комментариями на регулярной основе, в соответствии с:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Выберите систему документации, такую ​​как Doxygen, и придерживайтесь ее. Продолжайте проверять представленные документы.
2. Попробуйте представить кого-то новичка в кодовой базе, который входит и читает ваши документы, могут ли они начать с него? Стажеры на самом деле хороши для этого, сядьте на новую с имеющейся у вас базой документов и простой задачей и посмотрите, как далеко они продвинулись, если они споткнулись, много уверенности в том, что все, что вы им сказали, чтобы они снова пошли, идет в документах.
3. Сделайте комментарии к документации контрольной точкой в ​​ваших процессах проверки.

Читатели кода обычно пытаются ответить на три вопроса:

1. Что делает этот класс или функция? Если на это сложно ответить, значит, это слишком много. Код, который трудно документировать, обычно просто неверен.
2. Как мне это использовать? Пример может быть достаточно хорошим.
3. Этот код удивителен. Почему ты это сделал? Скорее всего ответы: обойти ошибку в сторонних компонентах, потому что очевидный метод оказался слишком медленным

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

Если я увижу «двойную длину», я спрошу: «Какая единица измерения?» Не добавляйте комментарий. Измените имя переменной. Если я вижу блок кода и говорю «что это делает?», Не добавляйте комментарий. Извлеките функцию со значимым именем. Если вы не можете извлечь функцию, потому что для этого потребуется 17 аргументов, выполните рефакторинг кода.