ong*_*oso 25 comments coding-style
Ber*_*t F 26
简短的回答
简短的回答是任何时候相对于阅读它的东西是不明显的.如果它的代码仍在不断变化,那么你就是唯一的消费者,只需为你评论(小时和天).准备办理登机手续以便其他人试用 - 为您和您的团队提供意见(数天和数周,可能是数月).准备广泛发布 - 对即时和未来公众(月和年)的评论.您必须将注释视为工具,而不是文档.
答案很长:
YesYesYes当我写作的时候？ - 是的
当你到达代码没有立即清除的地方时,随时删除评论.例如,在类名不清楚或可能解释得过于广泛时描述类.另一个例子是,如果我要编写一个非显而易见的代码块,我将首先添加一条注释,提醒我我想要/需要什么.或者,如果我只是添加了一些代码,我立即意识到那里有一个问题,请发表评论以提醒自己.这些评论是实现者评论,不是为了帮助未来的维护者,而是为了帮助自己编写代码.
随时随地删除FIXME - explanation和TODO explanations提醒.
代码仍在不断变化,所以我还没有记录每一个方法和参数.
我完成一部分后(Single class/function/if-elses)？ - Yes
当我合理地完成一个方法或类时,现在是时候审查它了.除了检查方法范围,排序方法和其他代码清理以提高可理解性之外,现在是时候开始根据团队标准对其进行标准化.根据将要发布的受众群体考虑需要哪些评论(未来您也是受众群体的一部分!)该类是否有标题块？是否存在不应该调用此方法的非显而易见的条件？此参数是否有任何条件,例如不应为null？
检查FIXME和TODO项目 - 仍然有效？在继续之前你应该解决的任何问题？
这些仍然是您和您的团队的注意事项,但是未来维护人员的标准化笔记的开头.
在我完成整个工作之后？ - Yes
现在是时候审查所有内容并根据您的标准最终确定评论.
所有FIXME和TODO项目都已解决(修复或捕获为已知问题)？
这些说明现在适用于未来的维护者.
现在肮脏的小秘密
更多并不总是更好.与单元测试一样,您必须平衡工具的使用权衡成本与收益.事实上,编码器每小时只能输入这么多物理线路 - 应该注释多少百分比？较低的百分比意味着我有很多代码,但它令人困惑,难以理解和正确使用.较高的百分比意味着,在某人更改方法签名或重新定义界面的一小时内,所有时间都花在完全评论那些被破坏的方法的每个参数上.
根据代码的稳定性,生存时间以及发布的广泛程度找到合适的百分比.还不稳定 - 最少的评论可以帮助您和您的团队.稳定并为项目做好准备 - 完全评论.公开发布？ - 完全评论(再次检查!)版权(如果适用).获得经验后,调整百分比.
小智 12
你永远不应该"添加"评论 - 它们不是补充.注释是代码的一部分 - 您可以在需要时使用它们.询问何时应该添加它们就像询问何时应该添加函数或类一样.考虑到这一点,我记得在大学里做了一个项目建议,我曾为其中一名学生带来了大约1000行Pascal,没有任何功能.当我询问他为什么没有使用函数时,他的回答是"我将在以后添加它们,一旦我使用了它."
这是一种风格问题.就个人而言,我喜欢在编码期间写评论,而不是之后.因为我把它留给以后,我通常会变得懒惰而根本不写它们.也就是说,有时候查看完成的代码是很有用的,找出代码本身不明显的内容并记录下来.特别是,做出假设的部分.