python 注释出错_代码注释出错

最新推荐文章于 2021-06-21 22:19:50 发布

danpu0978

最新推荐文章于 2021-06-21 22:19:50 发布

阅读量961

点赞数

文章标签： java python javascript 人工智能 linux ViewUI

版权

python 注释出错

添加代码注释应该是一种好习惯，但这就是为什么它经常失败的原因：

首先，将您的良好意图写成简单易读的代码。

编写自我描述代码！您的代码应像句子一样阅读。避免使用智能捷径和技巧，因为它们会破坏阅读效果。希望读者具有扎实的编程知识，但不了解代码的用途。如果代码太紧凑，则添加额外的代码步骤对其进行记录，例如：

...
final Person dummyPerson = new Person("Joe", "Bloggs");
return dummyPerson;

而不是使用注释：

...
// Return dummy person.
return new Person("Joe", "Blogs");

好的，这个示例有点愚蠢，但是您明白了。

我不同意使用长名的做法。优先使用长的显式名称，而不是需要代码注释的短的无意义的名称。有时长名称确实很烦人，例如当它们在某种算法中始终出现在各处时，在这种情况下，您可以使用注释。

考虑使用更多列：

默认的最大80列是可怕的，使用宽屏并使用120列或更多列，代码将更易读，因为长行将不再换行，并且您可以使用更长的更明确的名称。

使用断言来记录前后的条件，而不是冗长的注释。

public List<String> listFiles(final String folderUrl) {
assert folderUrl!= null;
assert folderUrl.endsWith("/");
  ...
}

如果您编写API，则必须提供良好的文档，但是对于内部代码，我认为注释不应取代良好的命名和代码清晰度。当代码不是真正的自我记录时，我使用代码注释。注释应该传达什么代码不能。他们应该解释做出特定设计决策的原因，应该解释应该实现什么代码以及为什么要这样做。

了解如何使用Javadoc，它不仅看起来更好，而且还可以帮助自动更新一些文档。引用代码时，请尝试使用链接标记。您的IDE可能会在重命名过程中自动更新链接的方法和类名，以确保您的某些文档保持最新。

/**
* Use the link tag: {@link SomeClass#someMethod}
*/

链接：

参考： Javarizon博客上我们的JCG合作伙伴 Christophe Roussy的代码注释出了错。

翻译自: https://www.javacodegeeks.com/2012/05/code-comments-gone-wrong.html

python 注释出错

关注