Существуют ли стандартные форматы комментариев в коде?

Мне интересно, есть ли у людей стандартный формат комментариев в своем коде. Не такие вещи, как комментарии xml для метода или класса, а скорее комментарии внутри метода.


См. также:

Есть ли стандартный (например, phpdoc или pythons docstring) для комментирования кода С#?

Ответ 1

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

  • Не просто повторите то, что делает код. Например,
 // Start the services
 StartServices();

- ужасный комментарий!

  1. Опишите почему. Почему код делает то, что он делает? Что такое бизнес-предположение или алгоритм?

  2. Отформатируйте свои комментарии для максимальной читаемости. Вставьте их правильно, оставьте места, где это необходимо, и т.д.

  3. Если кто-то уже начал комментирование стандартным способом, не нарушайте этот стандарт.

  4. Ознакомьтесь с этой статьей в MSDN о написании эффективных комментариев: http://msdn.microsoft.com/en-us/library/aa164797.aspx

Ответ 2

// I usually write comments like this

Когда я работаю, для большинства деклараций (классов, методов, некоторых свойств) требуется использовать стандартный стиль комментария xml (мы используем С#).

Иногда вы можете видеть комментарии заголовка/нижнего колонтитула.

/****************************************************/
// Filename: Customer.cpp
// Created: John Doe
// Change history:
// 18.12.2008 / John Doe
// 14.01.2009 / Sara Smith
/****************************************************/

/* Here goes a lot of stuff */

/****************************************************/
// EOF: Customer.cpp
/****************************************************/

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

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

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

/// <summary>
///     Handles the standard PageLoad event
/// </summary>
/// <param name="sender">
///    Event sender
/// </param>
/// <param name="e">
///    Event arguments
/// </param>
public void Page_Load (object sender, EventArgs e)
{
    // Do something here
}

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

Мое личное мнение - добавлять комментарии, когда вам есть что сказать или объяснить, а не только для того, чтобы комментировать все.

Ответ 3

/**
 * block comments to document a method for javadoc go like this
 * @param
 * @return
 * @exception BTKException
 * @see BTK
 */

Ответ 4

Прокомментируйте строку над кодом (блоком), которая делает то, что вы описываете

// This is a comment.
Some code goes here

Избегайте делать такие вещи, как

// ----------------
// IMPORTANT COMMENT
// ----------------

И я не использую

/* comment */

И, возможно, самое главное, очистить комментарии! Комментарий, который описывает несуществующую функциональность, хуже, чем вообще никаких комментариев.

Ответ 5

Не могу поверить, что мы пропустили ключевое слово REM.

Хотя, честно говоря, это для ЗАМЕЧАНИЯ, а не КОММЕНТАРИЙ.

Ответ 6

//For one line, I write them like this

/*
For multiple lines of text
I write them like this
*/

/*
for(multiple lines of code){
  I.WriteComents(With("//"));
  Reason==If(I.Remove('The top begin-quote mark') then
    I.Worry.Not('About removing the close-quote mark');
//*/

Ответ 7

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

В общем, комментарии внутри кода должны соответствовать четырем правилам:

  • Они не должны указывать очевидные
  • Они должны соответствовать тому, что они описывают
  • Должно быть понятно, что они описывают (например, какая строка, блок).
  • Они должны быть прочитаны любым будущим сопровождающим.

При этом часто возникает тенденция размещать информацию, которая важна для вызывающих, как внутренний комментарий. Например: "OOPS, это не обрабатывает отрицательные числа". Всякий раз, когда вы видите внутренний комментарий, пересматриваете, нужно ли обновлять документацию заголовка или использовать инструмент, который "подталкивает" комментарии к осознанию вызывающих функции функций (я есть такой инструмент для Java).

Ответ 8

/* I will sometimes write
comments like this */

Ответ 9

# ----------------------------------
# BIG IMPORTANT COMMENTS IN PERL/SH
# ----------------------------------

Ответ 10

' I usually write comments like this

Ответ 11

<!--How about comments like this!?-->

Ответ 12

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);

Ответ 13

(* Modula-2 comments go like this *)

Ответ 14

/*
 * Brief summary of what going on.
 */
int code_that_goes_on(int c)
{
     /* and then if I have to remark on something inside... */
     return 0;
}

99% компиляторов будут поддерживать комментарии //, что является удивительным, но 1% все еще существует, и это не слишком сложно сделать жизнь пригодной для жизни.

EDIT: комментарий Delphi немного тупой, но указывает на реальный недостаток. Я намереваюсь, чтобы это был C-специфический ответ.

Ответ 15

На эту тему могут быть религиозные войны.

То, что я пытаюсь сделать, что не вызывает слишком много войны,

 // explain the purpose of the following statement in functional terms
... some statement ...

Идея заключается в том, что если я запускаю код через программу, которая удаляет все, кроме комментариев, то, что осталось, является довольно хорошим псевдокодом.

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

 /*
 ... some code ...
/**/

затем измените первую строку - либо удалите ее, либо измените ее на /**/

 /**/
... some code ...
/**/

Ответ 16

Если вы параноикны и не используете или не контролируете контроль источника, вы можете сделать это

// Initials-YYMMDD-fixNo-Start
dosomething();
// Initials-YYMMDD-fixNo-Finish

Это делает кровавый большой беспорядок, но он дает вам некоторый способ отменить изменения.

Но я бы предложил использовать источник управления

Ответ 17

Мне нравится делать такие вещи:

/************
*  Comment  *
************/

Таким образом, мне приходится тратить время на переформатирование всего блока в любое время, когда я добавляю/удаляю текст

Ответ 18

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

Для создания документации с ваших классов С# посмотрите Sandcastle.

Ответ 19

Стандарты комментариев наиболее полезны, когда комментарий будет анализироваться внешним инструментом (обычно, генератором документов, например javadoc).

В этом случае внешний инструмент будет указывать стандарты.

В других случаях см. Как вам нравятся ваши комментарии? (Лучшие практики)

Ответ 20

В C/С++/С#/Java, когда у меня есть комментарий, объясняющий блок кода:

// comment
code;
more_code;

когда комментарий объясняет одну строку:

code; // comment

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

Ответ 21

Один стиль комментариев в С++/Java и т.д.:

// Use // for all normal comments...
// and use multiline comments to comment out blocks of code while debugging:
/*
for(int i = 0; i < n; ++i) {
    // If we only use // style comments in here,
    // no comment here will mess up the block comment.
}
*/

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

Ответ 22

Мой код самодокументирован. Мне не нужны комментарии.

Ответ 23

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

например doxygen:

http://www.stack.nl/~dimitri/doxygen/docblocks.html

/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */

Ответ 24

Я удивлен, что не больше людей рекомендуют doxygen. Это хороший способ документирования кода, с побочным эффектом, который он может автоматически генерировать html + pdf API-документацию в конце дня.

Ответ 25

Я предпочитаю комментировать этот способ для функции

/**
 * Activates user if not already activated
 * @param POST string verificationCode
 * @param POST string key
 * @return true on success, false on failure
 * @author RN Kushwaha <[email protected]>
 * @since v1.0 <date: 10th June 2015>
 */

public function activateUserAccount() {

//некоторый код здесь

}

Я использую комментарий одиночной строки для описания кода, например

//check if verificationCode exists in any row of user table
code here

Ответ 26

- Обычно я пишу такие комментарии

в SQL