如何使注释与代码保持一致?[复制品]

正如您所说的,注释应该表达代码中不明显的内容(代码保持原样的原因、尝试过的方法以及发现的导致代码变成现在这样的缺陷等)

但在更一般的意义上,可以把代码看作是逻辑地分组到相关的块中。名称空间、类、方法、块、行。这些块构成了应用程序的层次结构概述。因此,通过注释块并给出 概述 对于他们所做的工作,您可以对代码进行总结,使其他人能够快速轻松地找到与他们相关的部分,理解它,然后有效地使用或修改它,并将失败的风险降到最低。

所以解释那个文件。打开打开一个文件是没有用的。

但是解释10行代码块将定位、打开、读取和存储应用程序的首选项时,可以节省读者实际读取和解码全文的时间。简而言之,他们可以理解代码的全部用途,并知道是否需要深入研究。或者,如果他们希望调用代码,他们将再次理解代码的功能和使用方法,而不需要深入研究它如何实现其行为的更精细细节。

因此,在任何重要代码块(在上面描述的任何/所有级别)的开头都需要注释,其中摘要将节省读者阅读代码的时间,以便合理地理解它的功能。在任何需要对代码进行注释的地方,解释它如何或为什么执行它的功能。

请记住,您的注释是向以前从未见过该代码的人描述代码。当你在6个月内再次访问它时。几句精心挑选的话可以省去 小时 试图破解一些密码的工作。

如果你在6个月后来看你的代码,你可能会觉得对自己来说不太直观,只需要评论一下就可以了!

通过这种方式,你正在帮助你未来的自己(一般来说,你将是那个稍后访问代码的旧部分的人)以及其他可能正在维护你的代码的人:)

当你发现自己想要包含一个评论时,问问自己,为什么评论的部分不在它自己的方法中,而在它自己的方法名中……这样,您就可以通过方法名对代码进行注释,并将其分解为更小的步骤,使其更清晰。