评论做法？

Question

作为一名计算机工程专业的学生,​​我一直被迫为我所做的一切打上非常详细的评论.我可以看到这对团队项目或工作场所非常有用,但是当你在自己的项目上工作时,你会花多少时间评论？

作为一个我正在努力的个人项目变得越来越复杂我有时觉得我应该更多地评论,但我也觉得好像浪费时间,因为我可能是唯一一个正在努力的人.值得花时间和杂乱的代码吗？

思考？

编辑:这给了我很多思考.感谢您的输入!我没想到会有这么大的回应.

Answer 1

当代码不能时,考虑周全的评论会有所启发.经过深思熟虑的功能和变量名称消除了对大量注释的需求.如果您发现有必要对所有内容进行评论,请考虑简化代码.

Answer 2

如果你看过你6个月前写的代码,你会想知道为什么你没有更好的评论.

Answer 3

如果代码写得很好,使用简短的方法(参见组合方法模式)和有意义的名称,那么代码只需要很少的注释.只有解释"为什么"的注释才有用 - 解释"什么"的注释应该通过改进代码来代替它显而易见的.不应将注释用作编写错误代码的借口.

公共API,特别是在封闭源应用程序中,可能是推荐使用全面javadoc的唯一地方 - 然后您需要努力维护它们并使它们始终保持准确和最新.误导或过时的评论比没有评论更糟糕.最好通过为其编写测试并使用好的名称进行测试来记录代码的作用.

清洁代码一书有很好的评论章节.