代码中是否有标准的注释格式？

I'm wondering if people have a standard format for comments in their code. Not things like xml comments for a method or class but rather comments within a method.

我想知道人们的代码中是否有标准的评论格式。不是像方法或类的xml注释,而是方法中的注释。

26 个解决方案

#1

You should really consider a couple things to make good comments beyond formatting.

除格式化之外,你应该考虑一些事情来做出好的评论。

Do not simply restate what the code is doing. For example,

不要简单地重述代码正在做什么。例如,

 // Start the services
 StartServices();

is a frigging terrible comment!

是一个可怕的评论!

Describe why. Why is the code doing what it's doing? What's the business assumption or algorithm step?

描述原因。为什么代码正在做它正在做的事情?什么是业务假设或算法步骤?
Format your comments for maximum readability. Tab them properly, leave spaces where necessary, etc.

格式化注释以获得最大可读性。正确标记它们,在必要时留出空间等。
If someone has already started commenting in a standard way, don't break that standard.

如果某人已经开始以标准方式发表评论,请不要违反该标准。
Check this article on MSDN about writing effective comments: http://msdn.microsoft.com/en-us/library/aa164797.aspx

在MSDN上查看有关编写有效注释的文章:http://msdn.microsoft.com/en-us/library/aa164797.aspx

#2

// I usually write comments like this

Where I work it is required to use standard xml comment style for most of the declarations (classes, methods, some properties) (we use C#).

我工作的地方需要对大多数声明(类,方法,一些属性)使用标准的xml注释样式(我们使用C#)。

Sometimes you can see header/footer comments in use.

有时您可以看到正在使用的页眉/页脚注释。

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

Something like this was used at one of my old places of work. In my opinion too much of unnecessary stuff. Change history is nicely seen these days through a version control system.

在我以前的一个工作场所使用过类似的东西。在我看来太多不必要的东西。如今,通过版本控制系统可以很好地看到更改历史记录。

In many good software shops there are internal guidelines as to when and how to write comments. Documents are typically referred to as "Source code style policy" or something. It is very important to adhere to one common style in commenting the code.

在许多优秀的软件商店中,有关于何时以及如何撰写评论的内部指南。文档通常被称为“源代码样式策略”或其他东西。在评论代码时坚持一种共同的风格是非常重要的。

Of course this commenting hype shouldn't go too far as to comment every little piece of code, especially the obvious ones.

当然,这种评论炒作不应该过于评论每一小段代码,特别是明显的代码。

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

This one is a good example of over-obsession with commenting. Something like this adds exactly zero information but only adds noise to the source file. And we have to do it at work as required.

这是一个过度迷恋评论的好例子。像这样的东西只添加零信息,但只会增加源文件的噪音。我们必须按要求在工作中这样做。

My personal opinion is add comments when you have something to say or explain, not just for the sake of commenting everything.

我个人的意见是当你有话要说或解释时添加评论,而不仅仅是为了评论一切。

#3

Comment on the line above the code (block) that does what you're describing

评论代码(块)上方的行,它执行您所描述的内容

// This is a comment.
Some code goes here

Avoid doing stuff like

避免做像这样的事情

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

And I avoid using the

我避免使用

/* comment */

And perhaps most importantly, clean up comments! A comment that describes non-existent functionality is worse than no comment at all.

也许最重要的是,清理评论!描述不存在的功能的评论比根本没有评论更糟糕。

#4

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

#5

I can't believe we missed the REM keyword.

我不敢相信我们错过了REM关键字。

Though to be fair, it's for REMARK not COMMENT.

虽然公平,但对于REMARK没有评论。

#6

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

#7

The problem with comments within a method (rather than in an interface), is that they are actually not meant to be seen by anyone except for people maintaining that method. Therefore, there is no real need for a standard for the comments. They don't get published anywhere, they're not publicly visible, callers will generally never see them.

方法中的注释(而不是在界面中)的问题在于,除了维护该方法的人之外,任何人都不应该看到它们。因此,没有真正需要评论的标准。它们不会在任何地方发布,它们不会公开显示,呼叫者通常永远不会看到它们。

In general, comments inside code should follow four rules:

通常,代码中的注释应遵循以下四条规则:

They should not state the obvious

他们不应该说明显的

They should be consistent with what they describe

它们应与他们描述的内容保持一致

It should be clear what they describe (e.g., which line, block).

应该清楚他们描述了什么(例如,哪一行,阻止)。

They should be readable by any future maintainer.

任何未来的维护者都应该可以阅读它们。

That being said, there is often a tendency to place information that is important to the callers as an internal comment. For example: "OOPS, This doesn't handle negative numbers". Whenever you see an internal comment, reconsider whether the header documentation should be updated, or use a tool that "pushes" the comments to the awareness of function callers (I have a tool like that for Java).

话虽如此,但往往会将对呼叫者重要的信息作为内部评论。例如:“OOPS,这不处理负数”。每当你看到一个内部评论时,重新考虑是否应该更新标题文档,或者使用一个工具将注释“推”到函数调用者的意识(我有一个类似于Java的工具)。

#8

/* I will sometimes write
comments like this */

#9

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

#10

' I usually write comments like this

#11

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

#12

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);

#13

Comments standards are most useful when the comment will be parsed by an external tool (usualy, a document generator, like javadoc).

当注释将由外部工具(通常是文档生成器,如javadoc)解析时,注释标准最有用。

In this case, the external tool will state the standards.

在这种情况下,外部工具将说明标准。

For other cases, see How do you like your comments? (Best Practices)

对于其他情况,请参阅您对评论的评价方式如何? (最佳实践)

#14

(* Modula-2 comments go like this *)

#15

If you are paranoid and don't use or trust source control, you might do this

如果您是偏执狂并且不使用或信任源代码控制,您可能会这样做

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

It makes a bloody big mess, but it gives you some way to rollback changes.

它造成了一个血腥的大混乱,但它为你提供了一些回滚变化的方法。

But I'd suggest using source control

但我建议使用源代码控制

#16

There can be religious wars on this subject.

在这个问题上可能会发生宗教战争。

What I try to do, that doesn't cause too much warfare, is

我试图做的,不会引起太多的战争,是

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

The idea is, if I run the code through a program that deletes everything except the comments, what is left is pretty good pseudocode.

我的想法是,如果我通过删除除注释之外的所有内容的程序运行代码,剩下的就是相当不错的伪代码。

Something that's useful as a way to comment out code that you think you might need again is:

作为一种有用的注释掉你认为可能需要的代码的方法是:

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

then modify the first line - either delete it, or change it to /**/

然后修改第一行 - 删除它,或将其更改为/ ** /

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

#17

/*
 * 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% of compilers will support // comments, which is awesome, but that 1% still exists, and it's not too difficult to make life livable for them.

99%的编译器会支持//评论,这很棒,但1%仍然存在,并且让他们为生活变得适宜并不困难。

EDIT: The Delphi comment is a bit obtuse, but does point out a real deficiency. I intend this to be a C-specific answer.

编辑:德尔菲的评论有点迟钝,但确实指出了一个真正的缺陷。我打算将此作为特定于C的答案。

#18

I like to do things like this:

我喜欢做这样的事情:

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

That way i have to waste time reformatting the entire block any time I add/remove text

这样我每次添加/删除文本时都不得不浪费时间重新格式化整个块

#19

I don't think there is a standard for what you are asking. And I don't see how it would add any benefit from /// comments on the method itself.

我不认为你问的是什么标准。我不知道如何从///注释方法本身中获得任何好处。

For creating documentation from your C# classes take a look at Sandcastle.

要从C#类创建文档,请查看Sandcastle。

#20

In C/C++/C#/Java, when I have a comment explaining a block of code:

在C / C ++ / C#/ Java中,当我有一个解释代码块的注释时:

// comment
code;
more_code;

when a comment is explaining a single line:

当评论解释一行时:

code; // comment

I usually use // for single sentence comments and /* ... */ comments for multi-sentence comments.

我通常使用//用于单句注释和/ * ... * /注释用于多句注释。

#21

One comment style in C++/Java etc is this:

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

I think it is an interesting point, even if it's not that incredibly useful.

我认为这是一个有趣的观点,即使它不是那么有用。

#22

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

我的代码是自我记录的。我不需要评论。

#23

There are packages that will help write and format documentation. They require some specific changes so they can identify classes of comments.

有些软件包可以帮助编写和格式化文档。它们需要一些特定的更改,以便识别注释类别。

such as doxygen:

如doxygen:

http://www.stack.nl/~dimitri/doxygen/docblocks.html

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

#24

I'm surprised that not more people recommended doxygen. It is a good way of documenting code, with the side effect that it can automagically generate html + pdf API documentation at the end of the day.

我很惊讶没有更多的人推荐doxygen。这是一种记录代码的好方法,其副作用是它可以在一天结束时自动生成html + pdf API文档。

#25

I prefer commenting this way for function

我更喜欢用这种方式评论功能

/**
 * Activates user if not already activated
 * @param POST string verificationCode
 * @param POST string key
 * @return true on success, false on failure
 * @author RN Kushwaha <rn.kuswaha@gmail.com>
 * @since v1.0 <date: 10th June 2015>
 */

public function activateUserAccount() {

public function activateUserAccount(){

//some code here

//这里有一些代码

}

I use single line comment for code descriptions like

我使用单行注释代码描述

//check if verificationCode exists in any row of user table
code here

#26

-- I usually write comments like this

- 我经常写这样的评论

in SQL

#1