我应该何时向我的代码添加注释？ [英] When should I add comments to my code?

问题描述

• 当我写作时？


• 在我完成一个部分之后（单个课程/功能/ if- elses）？


• 在我得到整个工作之后？

解决方案

简短的答案

简短的答案是任何时候，相对于谁将要阅读它是不明显的。如果它的代码仍然在流量，所以你是唯一的消费者，只是对你的评论（小时和天）。准备检查其他人尝试 - 为您和您的团队（天和周，可能几个月）的评论。准备好广泛发布 - 对即时和未来的公众（月和年）的意见。您必须将评论视为工具，而不是文档。

长答案：

• 当我写作时？ - 是


• 在我完成部分工作之后（单课/函数/ if- elses）？ - 是


• 在我得到了整个工作？ - 是

当我写作？ - 是

当您遇到代码无法立即清除的地方时，请删除评论。例如，当类名不清楚或可以解释得太广泛时，描述类。另一个例子是如果我要写一个非明显的代码块，我将首先添加一个注释提醒我我想要/需要。或者如果我只是添加了一些代码，我马上意识到有一个骗子，在那里，发表评论提醒自己。

删除 FIXME - 解释和 TODO说明提醒。

代码仍在流动，

在我完成了一个部分之后（单个类/函数/ if-elses）？ - 是

当我合理地使用方法或类时，审查它。除了检查方法，排序方法和其他代码清理的范围以提高可理解性，现在是开始根据团队标准进行标准化的时间。考虑什么评论需要基于受众将被释放（未来你是观众的一部分！）类有头块吗？是否存在不明显的条件，在此条件下不应调用此方法？此参数是否有任何条件，例如不应为null？

检查 FIXME 和 TODO 项目 - 仍然有效？

这些仍然是您和您的团队的注释，但是未来维护者的标准化注释的开始。

我得到了整个工作？ - 是

现在是检查所有内容并根据您的标准完成评论的时候。 p>

所有 FIXME 和 TODO 已知问题）？

这些笔记现在是为未来的维护者。

更多不总是更好。像，您必须平衡使用您的工具称重成本和效益。事实是，编码器每小时只能输入如此多的物理线路 - 应该是多少百分比的评论？低百分比意味着我有很多代码，但它的混乱和难以理解和使用正确。较高的百分比意味着，在有人更改方法签名或重新定义界面的一个小时内，所有时间都会对这些方法的每个参数进行完全注释。

根据代码的稳定性，它将运行的时间以及它将被发布的广泛程度，找到正确的百分比。不稳定 - 最小的评论，以帮助你和你的团队。稳定并准备好项目 - 完全评论。公开发布？ - 完全评论（再次检查！）与版权（如果适用）。当你获得经验时，请调整百分比。

• When I'm writing it?
• After I got a part done (Single class/function/if-elses)?
• After I got the whole thing working?

解决方案

The short answer

The short answer is anytime something is non-obvious relative to whose going to be reading it. If its code that is still in flux so you are the only consumer, just comments for you (hours and days). Ready to check in for others to try out - comments for you and your team (days and weeks, possibly months). Ready for wide release - comments for the immediate and future public (months and years). You have to think of comments as tools, not documentation.

The long answer:

• When I'm writing it? - Yes
• After I got a part done (Single class/function/if-elses)? - Yes
• After I got the whole thing working? - Yes

When I'm writing it? - Yes

Drop comments anytime you hit a place where the code isn't immediately clear. For example, describe the class when the class name isn't clear or could be interpreted too widely. Another example is if I'm about to write a non-obvious code block, I'll first add a comment reminding me of what I want/need. Or if I just added some code and I immediately realized there was a gotcha in there, drop a comment to remind yourself. These comments are implementor comments, less to help future maintainers, but rather to help yourself in the coding process.

Drop FIXME - explanation and TODO explanations reminders as you go.

Code is still in flux, so I'm not yet documenting every and all method and parameter.

After I got a part done (Single class/function/if-elses)? - Yes

When I'm reasonably done with a method or class, now is the time to review it. Along with checking scopes of methods, ordering methods, and other code cleanup to improve understandability, now's the time to begin to standardize it against your team standards. Consider what comments are need based on the audience it will be released to (future you is part of the audience too!) Does the class have a header block? Are there non-obvious conditions under which this method should not be called? Does this parameter have any conditions on it, e.g. should not be null?

Check the FIXME and TODO items - still valid? Any you should address now before moving on?

These are still notes for you and your team, but the beginnings of standardized notes for future maintainers.

After I got the whole thing working? - Yes

Now is the time to review everything and finalize comments against your standards.

All FIXME and TODO items addressed (fixed or captured as known issue)?

These notes now are for future maintainers.

Now the dirty little secret

More is not always better. Like unit tests, you have to balance use of your tools weighing costs vs benefits. The fact is that a coder can only type so many physical lines per hour - what percent should be comments? A low percentage means I've got a lot of code, but its confusing and difficult to understand and use correctly. A high percentage means that, in an hour when someone changes a method signature or redefines an interface, all the time is spent fully commenting every parameters of those methods just got trashed.

Find the right percentage based on the stability of the code, how long it will live, and how widely it will be released. Not stable yet - minimal comments to help you and your team. Stable and ready for project - fully commented. Public release? - fully commented (check again!) with copyrights (if applicable). As you gain experience, adjust the percentage.

这篇关于我应该何时向我的代码添加注释？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！