您对代码注释中的句点/句号有何看法?[关闭]


27

在SO Tavern中看到了这个问题,所以我在这里发布问题。我认为这是一个有趣的问题。(当然,它不属于SO,但是我认为在这里还可以。)

您是否在代码注释中添加了句点(或者,正如OP所写,“句号”)?

为了保持相关性,为什么


2
有时我会做,有时我不会。这取决于评论以及易于阅读的内容。
蒂姆(Tim)2010年

Answers:


29

句号用于结束句子,但是如果注释只包含一个被代码包围的句子,那么我认为句号是不必要的。有时我什至不大写首字母。另一方面,详细的多行注释确实需要完整的标点符号。

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

4
+1。这看起来很像我的评论风格,给了我一个虚假的似曾相识的感觉。:)
Bobby Tables 2010年

26
不,句号用于标记句子的结尾。拥有一个或多个无关紧要。
Rook:

2
<joke>检查是否超出int边界会更好吗?</ joke>
Dan Rosenstark 2010年

2
@Yar:平均值始终在a和b之间,根据定义,平均值始终在边界之内,对吗?;)
mojuba 2010年

8
我所有的字符串都以null终止,因此适当的注释应始终以'\ 0'结尾。您不希望下一个看您的代码的人读完他的书吗?
CodexArcanum 2010年

26

是的,因为注释是英文的,并且正确的英文使用标点符号。


2
短信怎么样?
Moshe 2010年

4
@Moshe,短信很难说是英文。
Dominique McDonnell

8
英文不太好,但我仍然在其中使用标点符号。标点符号可以引导读者确切地了解作者的意图-这适用于任何语言,恕我直言。
cjmUK 2010年

@cjmUK,大声笑,是的,我也是。我认为这是我们不使用标点符号的原因,因为我经常收到诸如“ wd b gr8 cu there再见”之类的消息,这使我无所适从
Dominique McDonnell

我一路无路
cjmUK 2010年

17

您是否在代码注释中添加了句点(或者,正如OP所写,“句号”)?

为了保持相关性,为什么?

出于同样的原因,我在编写“普通”文本时添加了它们-它们是书写语言的一部分,因此它们不应该有什么特别之处。在写一个句子(一行)注释以及整个段落时,我会平等地使用它们。

源代码不是普通文本,因此我们使用不同的规则。简单;-)


我的一个朋友从来没有将电子邮件中的单词大写...因为它在互联网上。对我来说,当您使自己的文字适应SMS等技术限制时就很好了,但是电子邮件或源代码与信件和书本中的文本有何不同?
LennyProgrammers

1
@ Lenny222-不知道您在这里问什么。电子邮件应像普通文本一样写;就像你在写一封信一样。它们的实际编写方式(和SMS,哦,天哪,别让我开始使用SMS :)源代码没有遵循与普通文本相同的规则,因为它具有自己的语法规则。
Rook

2
对我来说,源代码注释是供人类阅读的。为什么某些信息是在单独的规范文档中还是嵌入在源代码注释中,为什么应该有所作为?
LennyProgrammers 2010年

@ Lenny222-我刚发生了什么事,所以我们之间没有误会。我们现在在谈论源代码,还是其中嵌入的注释?如果是第二种情况,那么我道歉,因为我误会了你。在这种情况下,规则与普通文本(用于注释)相同。在实际的源代码(由编译器/解释器读取的源代码)中,我看不出如何遵循相同的规则。
Rook

1
是的,我认为我们在不知情的情况下彼此同意。;)
LennyProgrammers 2010年

9

如果您发表评论,则希望它们以英文书写。在这种情况下,应该正确打标。否则会很懒。


1
句号是句子的结尾。评论不一定是完整的句子。
John B. Lambe

一般来说,评论应该是句子。如果没有,我应该问为什么不这样做。如果您的评论如此之短以至于它们不是句子,那么它们是否显而易见,因此是多余的?
quick_now

5

如果我写完整的句子(或更多),则可以。如果我不这样做,则有时不这样做,但通常还是可以。

我有时还会发疯,并使用感叹号,问号等;)

至于为什么,部分原因是因为我很特别,部分原因是我发现适当的标点可以增加很多清晰度。


如果使用问号,您是否理解自己的代码?
Moshe 2010年

@Moshe:当我可能还没有完全理解我自己的代码时,这些通常在TODO中。
亚当·李尔

2
@Moshe-为什么评论不能包含问题?问题可能很夸张。其实我经常我们吗?在我的评论中-在描述条件代码时,而不是对逻辑进行干式解释时,将逻辑描述为一个问题通常会更清楚。例如:“是否符合资格标准?如果否,则向用户显示警告。”
cjmUK 2010年

1
在处理大型项目和许多合作者时,我经常发现那些提出质疑的意见最为重要。
LennyProgrammers 2010年

3

其他答案及其受欢迎程度已经清楚地表明,长句中的句号会受到大家的赞赏,并且在单行中可能可以避免。

可能相关的另一点是避免使用感叹号,尤其是倍数。例:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

    // This code really sucks!

另一方面,问号有时非常有用:

    // TODO: What does Crojpler.bway() actually do?

1

这取决于。如果我写了一段大而恰当的段落来解释代码块的功能,那么我会像其他任何适当的文章一样正确地标点。OTOH,当我只注释一行代码时,我就不会。

为什么?-类似于为什么我用适当的写作方式写电子邮件,而我可能在SMS消息中使用速记句子。在一种情况下,我坐下来编写适当的文本块,因此我只是自动“正确地执行了它”,而在另一种情况下,这只是一个简单的注释。

我代码中的真实示例:

快速注释评论:

// check for vk_enter

“正确的”方法文档:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

.NET开发人员,对吗?;-)
Moshe 2010年

@Moshe:实际上是Java。这是一个非常大而复杂的applet的代码,除了它在浏览器中运行外,基本上就像一个桌面Swing应用程序。:)
鲍比表

虽然我说MDI是.NET术语。
Moshe 2010年

@Moshe:不,这是通用的(en.wikipedia.org/wiki/Multiple_document_interface)。
鲍比表

1

是的,我认为通过这种方式,您可以创建良好的编码约定,并且还可以为第三者查看您的代码创建清晰易读的代码。


1
那第二个人呢?
daviewales 2014年

0

在创建希望在IntelliSense生成的文档中看到的XML注释时,我将始终正确使用大写和标点符号。这些是更正式的构造,应这样对待。

但是,只是在代码块的主体中​​看到的注释应该尽可能地清晰。程序员如何实现这一目标取决于程序员。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.