这个评论结构叫啥名字？

Posted 2023-02-21

【中文标题】这个评论结构叫啥名字？

【英文标题】：What's the name for this comment structure?这个评论结构叫什么名字？

【发布时间】：2017-03-13 04:17:20

【问题描述】：

我一段时间以来第一次教授 C++ 编程课程，并且在某种程度上基于基本书籍示例，我发现学生希望他们的所有 cmets 都像这样结束：

for (int count = 1; count <= days; count++)    // Loop for each day
    organisms += organisms * increase;          // Compute organisms
    cout << organisms << endl;                  // Print out organisms

相比之下，我试图让他们使用专门的注释行，为此目的总结了几行代码：

// Update & display organisms for each day
for (int count = 1; count <= days; count++)  
    organisms += organisms * increase;          
    cout << organisms << endl;                  

后一种非行尾注释样式有合适的名称吗？

【问题讨论】：

不确定命名约定，但向他们展示示例i=i+1; // increment i 这是一个完美的示例 - 注释比代码长，除了代码之外什么也不告诉你。有趣的是为什么我们需要增加i？

"那些以代码缩进开始的 cmets" 或简称为 TCWSACI

离题了，但我们不应该更喜欢循环变量的半开范围吗？

告诉他们努力做到具体是一项永无止境的任务。例如，"Compute organisms" 并没有真正告诉我们计算是如何完成的原因。因此，更具体的评论是 “通过将当前的 organisms 与 increase 相乘，然后将其添加到当前的 organisms 并使用新值更新它来计算有机体。” ..（续）

我称这些 cmets 是多余且无信息的。对于任何有能力的程序员来说，它们并没有提高代码的可读性。更糟糕的是，没有对 cme​​ts 进行编译器检查，这意味着这些 cmets 可能会偏离使实际行为与预期行为模棱两可的代码。至于第二个代码块，代码前面的注释强烈表明代码属于单独的适当命名的方法。

【参考方案1】：

not 是您要求的注释结构的特定命名约定，而 // 表示 单行注释，而如何注释通常留给样式指南（如果有的话）有问题的来源。

尽管如此，这对于新程序员来说并不少见；一些我看过的例子：

if (some_array[i - 1] == 0)  // remember INDEX STARTS AT 0!!
    some_array[i - 1] = 1; // set to 1 if it equals 0

重要的是要教授评论的目的：注释。

例如，当您阅读某些材料时，可能会有某个单词的脚注¹，但²您³不会t⁴ 见⁵ a⁶ 脚注⁷ 详述⁸ 每⁹ word¹⁰.¹¹ 由于材料的作者希望读者对语言的语法和结构有基本的了解和理解，以便基本阅读它，但可能不了解其领域的特殊性。或者在源代码的情况下，可以将对语言有基本了解的普通读者可能无法理解的代码区域注释为example：

uint8_t temp;

// Rotate first row 1 columns to left  
temp           = (*state)[0][1];
(*state)[0][1] = (*state)[1][1];
(*state)[1][1] = (*state)[2][1];
(*state)[2][1] = (*state)[3][1];
(*state)[3][1] = temp;

学习编程的一部分是学习阅读代码并理解它在做什么，而不管 cmets 说什么，因为编译器不关心注释。

但是，即使在您自己的代码中，了解评论在凌晨 2 点的用处也很重要。

希望对您和您的学生有所帮助。

^{1 - 这解释了一点 2 - 介词-除 3 - 不是我 4 - 1个字的意思不会 5 - 观察者 6 - 字母表的第一个字母 7 - 脚注 .. 见脚注₇ 8 - 解释更多，或使车辆看起来不错 9 - 包罗万象 10 - 说真的，如果书籍像代码一样被评论，那将是一场噩梦 11 - 完全停止!!!!}