Question

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

另见：

Is there a standard (like phpdoc or python’s docstring) for commenting C# code?

Answer 1

除了格式化之外，你应该考虑做一些好的评论。

不要简单地重述代码的作用。例如，

 // Start the services
 StartServices();

是一个可怕的评论！

描述 为什么 。为什么代码正在做它正在做的事情？什么是业务假设或算法步骤？
格式化您的评论以获得最大可读性。正确地标记它们，在必要时留出空间等。
如果某人已经开始以标准方式发表评论，请不要违反该标准。
在MSDN上查看有关撰写有效评论的文章：http://msdn.microsoft.com/en-us/library/aa164797.aspx

Answer 2

// I usually write comments like this

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

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

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

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

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

当然，这种评论炒作不应过于评论每一小段代码，尤其是明显的代码。

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

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

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

Answer 3

对代码（块）上方的行进行注释，以执行您所描述的内容

// This is a comment.
Some code goes here

避免做像

这样的事情

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

我避免使用

/* comment */

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

Answer 4

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

Answer 5

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

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

他们不应该陈述明显的
他们应该与他们描述的内容保持一致
应该清楚他们描述的（例如，哪一行，阻止）。
任何未来的维护者都应该可以阅读。

话虽如此，通常会倾向于将对呼叫者重要的信息作为内部评论。例如：“OOPS，这不处理负数”。每当您看到内部评论时，都会重新考虑是否应更新标题文档，或者使用“推送”评论的工具来提醒函数调用者（I have a tool like that for Java）。

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

Answer 7

我无法相信我们错过了REM关键字。

虽然公平，但这不是评论。

Answer 8

/* I will sometimes write
comments like this */

Answer 9

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

Answer 10

' I usually write comments like this

Answer 11

当评论将由外部工具（通常是文档生成器，如javadoc）解析时，注释标准最有用。

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

对于其他情况，请参阅How do you like your comments? (Best Practices)

Answer 12

//Cheap Debugger

//Response.Write(MySQLStringBecauseINeedToKnowWhatsBroken);

Answer 13

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

Answer 14

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

我试图做的，不会导致过多的战争，

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

我的想法是，如果我通过删除除注释之外的所有内容的程序运行代码，剩下的就是非常好的伪代码。

用于评论您认为可能需要的代码的方法非常有用：

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

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

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

Answer 15

如果你是偏执狂，不使用或信任源代码控制，你可以这样做

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

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

但我建议使用源代码控制

Answer 16

/*
 * 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评论有点迟钝，但确实指出了一个真正的缺陷。我打算将此作为特定于C的答案。

Answer 17

我喜欢这样做：

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

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

Answer 18

我认为你所要求的标准并不存在。我不知道如何从方法本身的///评论中添加任何好处。

要从C＃类创建文档，请查看Sandcastle。

Answer 19

(* Modula-2 comments go like this *)

Answer 20

在C / C ++ / C＃/ Java中，当我有一个解释代码块的注释时：

// comment
code;
more_code;

当评论解释一行时：

code; // comment

我通常使用//用于单句评论，并使用/* ... */评论多句评论。

Answer 21

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 22

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

Answer 23

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

如doxygen：

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

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

Answer 24

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

Answer 25

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

/**
 * 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（）{

//这里有一些代码

}

我对

等代码描述使用单行注释

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

Answer 26

您可能至少要考虑对PHP Reflection类使用标准注释格式：https://www.php.net/manual/en/reflectionclass.getdoccomment.php

我的网站压缩html，所以像 //在这里评论在JS中将使Java脚本崩溃。在PHP中使用//的规范仅应作为“简短注释”，即：一行。我个人认为它们不应该用于多个行。

使用它们还使其无法压缩-或压缩起来比应压缩的要困难得多。

最后。

人的解释不是绝对的-计算机代码是：）

因此，如果您有需要或应该阅读的代码-（请放心），不要对其进行注释。即：强迫读者阅读代码，而不是依靠他们对注释的解释。

Answer 27

- 我经常写这样的评论

SQL中的

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

另见：

27 个答案: