你如何设定主要和次要评论的风格？

Question

有时我想编写一个“主要”注释来描述一大块代码，然后编写“次要”注释来描述该代码块中的一些行：

// Major comment

// Minor comment
...

// Minor comment 2
...

主要评论在没有代码的情况下看起来很奇怪，你无法直观地告诉它下面描述了多少代码。

你如何设定这些评论的风格？

（我记得很久以前在Code Complete中读到过这个，但我不拥有这本书。）

Answer 1

我对“主要”评论使用多行注释：

/*
 * yada yada yada
 */

并使用单行评论。

我知道有些人不喜欢使用/ * * / style注释，因为它会更难自动注释和取消注释块...但我喜欢它们的样子，而且我坚信代码应该是美学上令人愉悦。

这也意味着你应该能够在不阅读细节的情况下解析代码结构，这意味着我倾向于使用相当多的空格和分隔符注释行来帮助解决问题。所以对于我想评论的块我可能会写：

/**
 * detailed description ...
 */

code

// -- minor comment
code

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

Answer 2

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

// Minor comment
...

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

Answer 3

我使用这样的东西，使它看起来更像是以下代码块的“标题”或分隔符：

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

// Minor comment
...

// Minor comment 2
...

当然，假设“主要评论”只是几个字

Answer 4

我将主要注释放在代码（块）之上，前面是一个空行，有时候全部大写。我向右侧推出的小注释，缩进到第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.
 */

Answer 5

我认为“主要”和“次要”评论之间的区别在于它们附加的程序结构。例如，我将方法级或类级文档注释视为“主要”，将块级或行级注释视为“次要”：

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

我认为使用描述性名称和文档注释将功能单元重构为自己的方法是一种很好的做法，而不是用注释来编写代码。

Answer 6

这一切都以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.

Answer 7

我通常使用每个部分顶部的/* */来评论代码块。除了特殊情况（例如棘手的代码）之外，我不使用内联注释，因为我觉得注释是“隐藏的”，代码可以在以后扩展，注释必须是微管理的。例如：

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有三个主要部分：初始化，主循环和清理。在主循环中，我们获取令牌（预处理器或正常），将其插入树中，然后转到下一个令牌。

很可能每个部分都需要自己的[set]函数，所以很明显，如果部分变得笨重，你可能需要重构。

我应该补充一点，我格式化多行注释（我的“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（!）在他们之前，因为他们的使用是显而易见的，这是传统。=]）

Answer 8

我会这样做：

// 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＃中的问题是怎么回事。

Answer 9

// 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();
        }

Answer 10

主要评论

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

Answer 11

// 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();

当然，当语法不允许时，缩进技巧不适用（读取：Python）

Answer 12

这是我的评论风格偏好：

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