Как Вы разрабатываете главные и незначительные комментарии?

Я использую многострочные комментарии для 'главных' комментариев:

/*
 * yada yada yada
 */

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

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

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

/**
 * detailed description ...
 */

code

// -- minor comment
code

code
// --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- ---

// Major comment
// -------------
...

// Minor comment
...

... // Minor comment (end of line)

Я использую что-то вроде этого, чтобы заставить его больше походить на "заголовок" или разделитель для следующего блока кода:

// ***** Major comment *****

// Minor comment
...

// Minor comment 2
...

, Конечно, который предполагает, что "главный комментарий" является только несколькими словами

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

Для алгоритмических "дискурсов" я использую/* */как так:

/*
 * This is a long discourse on the code which follows it, usually
 * placed at the beginning of a method and containing information
 * which is not appropriate for the doc comments.
 */

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

/**
 * This is major comment describing the method
 */
public void foo() {
    if (...) {
        // minor comment describing block
        ...
        doSomething(); // minor comment describing line
    }
}

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

Это все симпатично C центральный здесь. В C/C++ я склонен писать

/* file -- what it is -*-emacs magic-*- */

Как первая строка.

/*
 * Block comments like this
 */

if( I need a comment on a code block) {
   /* I tend to write them like this */
   x = x + 1 ;                        /* ... and write my */
                                      /* line comments so */
}

я обычно резервирую // comments для внутреннего кода и сохраняю старые добрые комментарии BSD к комментариям блока.

В Lisp

;;;; Four semicolons for "file-scope" comments

;;; Three for block comments over a large chunk of code

(defun quux (foo bar)
    "Don't forget your docstrings, folks"
    ;; but big code comments get two semicolons
    (let ((a 1)
          (b 2))                      ; and only one semicolon
          (+ a b)))                   ; means an in-line comment.

# comment languages like Python and Ruby
# Have to live with one style of comment.
def quux(a,b):
    return a + b                          # poor neglected things.

Я обычно комментирую блоки кода с помощью /* */ наверху каждого раздела. Я не использую встроенные комментарии кроме специального curcumstances (например, хитрый код), потому что я чувствую, что комментарии "скрыты", и код мог быть расширен позже, и комментариями нужно будет микроуправлять. Например:

int parseEverything()
{
    /* Initialize the parser. */
    random_code_here();

    still_more_init();
        /// (Note: the above line still falls under the init section, even if it's separated by a newline.)

    /* Main parser loop. */
    while(!done_parsing) {
        /* Grab the token. */
        if(x) {
            /* Preprocessor stuff. */
            y();
        } else {
            /* Normal token. */
            z();
        }

        /* Insert into tree. */
        make_tree_node();
        insert_into_tree();

        /* Move to next token. */
        ++streamPtr;
            /// (Note: the above could be expanded to take up multiple lines, thus
            ///        if an inline comment were used it'd have to be moved, if
            ///        you even remember there's a comment there.)
    }

    clean_up();
}

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

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

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

я должен добавить, что форматирую многострочные комментарии как таковые (мой "IDE" (Vim) вставляет * в каждой строке для меня со сценариями по умолчанию (для моего дистрибутива), который удобен):

/*
 * This is a comment which normally would be on one line, but is either split into multiple
 * lines for emphasis or so we don't have 160-character hard-to-read comments everywhere.
 */

кроме того, я комментарий #else и #endif:

#ifndef FOO_H
#define FOO_H

#ifdef DEBUG
#else   /* DEBUG */
#endif  /* !DEBUG */

#endif  /* FOO_H */

, Но это добирается немного вне темы.

(#include защита не требует not (!) предшествовать им, потому что их использование очевидно, и это - традиция. =])

// A plate is displayed if a WorkFlowStepUpdate message is received
// whose:
//        * Change_Type is License_No
//        * Event_Type is GA, NA, or NG
//        * New_Value is non-null and non-blank
//        * Inspection_DateTime<(NOW-TimeInMinutesBeforeExpiringDisplaySignMessage)
//
// A plate is removed:
//         * if it has been displayed for TimeInMinutesBefore...
//         * a GA, NA, or NG CloseEvent is received  whose New_Value matches
//           a displayed plate
//
// If a plate is to be added to a full screen, the oldest plate on the display
// is removed to make room for the new plate.


.
.
.
.
.



// Record the ping status of each IP device
foreach (string s in th.Keys)
        {
        // We don't know if this is a wks or svr.
        // But we can rely on 0 being bad, and we'll
        // get the 'proper' state enumeration down in GetsOHInfo
        // 
        if (IsItLive(s)) IPStates[s] = 1;
        else IPStates[s] = 0;
        IPTimes[s] = System.DateTime.Now.ToUniversalTime();
        }

Главный комментарий

/***  Function - fooBar()  ****************************
** Description                                       **
**    does the flooble using the bardingle algorithm **
**      with the flinagle modification               **
** Pre-condition                                     **
**    all moths are unballed                         **
** Post-condition                                    **
**    all moths are balled                           **
******************************************************/
void fooBar( int foo ) {
    ...
    ...
}

/***  Function - fooBar() END  ***********************/

Незначительный комментарий

// note cast to int to ensure integer maths result
int i = (int)y / (int)x;

// Top-level (major) comment
theThing=doSomething();
    // - Second-level (minor) comment
    anotherThing=doSomethingWith(theThing);
        // - - Third-level (minor-minor?) comment
        yetAnotherThing=doSomethingWith(anotherThing);
    // - Back to second level
    destroy(anotherThing);
// Back to first level
helloWorld();

, Конечно, прием identation не применяется, когда синтаксис не позволяет его (чтение: Python)

Я сделал бы это как это возможно:

// Here we do it
//
// So, be aware this text is just to make a silly
// long comment to show how it would look like 
// in real code. 
doTheRealThing();

// and this is another thingy
doOtherThing();

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

// prepare for party
doIt();

// Here we do it
//
{
    // So, be aware this text is just to make a silly
    // long comment to show how it would look like 
    // in real code. 
    doTheRealThing();

    // and this is another thingy
    doOtherThing();
}

// another code that is not really affected by the comment
// above
die();

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

/**
 * This function will return the current object.
 *
 * And now it follows the normal long stuff that's again
 * a bit stretched to fill space...
 */
Object getCurrentObject();

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

#if 0
    Code in Here that's disabled
#endif

, И это также сохранит меня от наличия некоторого материала, который не является действительным кодом C++ (материал, промежуточный, те разделители все еще должны содержать допустимые маркеры). Я не уверен, как вопрос находится в C# об этом, все же.

Это - мое предпочтение стиля комментария:

/**
 * This is a comment explaining
 * what this method is actually doing
 */
public void foo()
{
    // this is a simple comment
    doSomething();

    // this is a special comment
    // explaining thoroughly what I'm doing
    // using as many words as possible
    // to be the most concise
    doSomethingSpecial();
}