你如何设计主要和次要的评论?

我对“主要”评论使用多行评论:

/*
 * yada yada yada
 */

对次要的使用单行注释。

我知道有些人不喜欢使用/**/style注释,因为这使得自动注释和取消注释块变得更加困难…但我喜欢它们的外观,我坚信代码应该是美观的。

这也意味着你应该能够在不阅读细节的情况下解析代码的结构,这意味着我倾向于使用大量的空格和分隔符注释行来帮助分解。因此,对于一个块,我想发表评论,我可以写:

/**
 * detailed description ...
 */

code

// -- minor comment
code

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

//主要注释
//———————————————————-
…

//次要注释
…

…//次要注释(行尾)

我使用类似的方法,使其看起来更像是以下代码块的“标题”或分隔符:

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

我认为“major”和“minor”注释的区别在于它们所附的程序结构。例如,我将方法级或类级文档注释视为“主要”,将块级或行级注释视为“次要”:

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

我通常使用 /* */ 在每个部分的顶部。我不使用内联注释,除非在特殊的curcumstance(比如复杂的代码)中使用,因为我觉得注释是“隐藏的”,代码可以在以后扩展,注释必须进行微观管理。例如:

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 有三个主要部分:初始化、主循环和清理。在主循环中,我们获取令牌(预处理器或normal),将其插入树中,然后继续下一个令牌。

很可能每个部分都调用自己的[一组]函数,因此很明显,如果部分变得庞大,您可能需要重构。

我要补充的是,我将多行注释格式化为这样(我的“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 S和 #endif S:

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

当然,当语法不允许时,识别技巧不适用(read: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++代码(这些分隔符之间必须包含有效令牌的东西)。不过,我不知道这件事是怎么回事。

这是我的评论风格偏好:

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