Есть ли стандартные форматы для комментариев в рамках кода?

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

, например doxygen:

http://www.doxygen.nl/manual/docblocks.html

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

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

My code is self-documenting. I need no comments.

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

// comment
code;
more_code;

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

code; // comment

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

Один из стилей комментариев в C ++ / 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.
}
*/

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

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

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

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

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

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

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

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

РЕДАКТИРОВАТЬ: комментарий Delphi немного тупой, но указывает на реальный недостаток. Я предполагаю, что это будет специфический для Си ответ.

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

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

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

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

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

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

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

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

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

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

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

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

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

в SQL

(* Modula-2 comments go like this *)

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

' I usually write comments like this

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

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

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

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

/* I will sometimes write
comments like this */

//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');
//*/

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

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

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

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

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

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

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

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

// This is a comment.
Some code goes here

Избегайте таких вещей, как

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

И я избегаю использования

/* comment */

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

// I usually write comments like this

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

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

/****************************************************/
// 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
}

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

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

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);