Question

我的计算机科学课程希望我开始描述性地评论我的代码，以便老师和其他学生在阅读时能够更好地理解它。 50％的懒惰和50％的精英，我不想要评论每一行，以便人们可以理解我的代码。除非确实有必要，否则我不想对每种方法进行评论（教师只需要他必须了解所需的内容而不必尝试解释各行代码）。在计算机科学领域被接受为足够的评论？＆＃34;

Answer 1

普遍接受的评论指南是：

非平凡的类应该有JavaDoc描述它们的用法/目的。记录对象的线程安全性也很常见。
基于方法名称的非平凡/非显而易见的方法应该具有JavaDoc。理想情况下，应注意对参数的任何要求（关于空值等的行为），以及对象中传递的任何修改。好的经验法则是回答：
- 此方法需要什么
- 它产生什么/保证（什么时候抛出异常）
- 修改内容（如果有的话）
应该注释任何复杂或不明显的代码行
- 这个魔法常数来自哪里
- 为什么要这样做（如果不是很明显）
必要时可以对类变量进行注释。这不太标准，但有时候注释变量以指示它的用途是有用的。

避免仅仅重复代码执行操作的注释。 E.g。

// Set x to 4 before the loop
x = 4;
for (int i = 0; i < x; i++)

但是，如果合适的话，请评论为什么要这样做：

// Set x to 4 since we are guaranteed to only have 4 threads
x = 4;
for ...

至少，你应该有好的方法评论（认为这是最重要的），并为你的课程提供粗略的概述评论。我会认为任何比这更不专业的事情和原因拒绝代码审查。

Answer 2

在Java中，注释用于从您编写的源代码生成javadoc。根据javadoc规范格式化您的评论。这足以在Java中发表评论，其他评论是可选的，有人提到评论与注释掉代码有关。如果您将此类代码保存在文件中，您最好留下合理的评论（即引用某些问题等）。请注意，使用Java命名约定和正确命名的Java元素可以大大减少在代码内部进行注释的需求。这些注释仅适用于证明读取或调试代码的用户，如上所述。其他可选注释与项目相关并标记为todo。您应该更多地关注javadoc注释，因为一般规则放在所有公共方法和类（包括接口）上。如果你的类实现了一些接口方法，那么你不应该在那里复制注释，只需引用相应的接口方法注释。

什么被认为是足够的评论？

2 个答案: