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

Question

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

---

Смотри также:

Существует ли стандарт (например, phpdoc или строка документации python) для комментирования кода C #?

Answer 1

' I usually write comments like this

Answer 2

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);

Answer 3

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

Answer 4

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

например, доксиген:

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

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

Answer 5

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

Answer 6

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

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

Answer 7

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

// comment
code;
more_code;

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

code; // comment

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

Answer 8

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

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

Answer 9

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

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

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

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

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

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

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

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

Answer 10

/*
 * 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 немного тупой, но указывает на реальный недостаток. Я предполагаю, что это будет специфический для Си ответ.