php 代码需要重写注释_不要注释错误的代码-重写它

php 代码需要重写注释

在这篇文章中，我将分享我通过阅读代码，编写代码和阅读书本获得的“代码注释”的经验。

让我们从著名的报价开始

 “Don't comment bad code—rewrite it.” 
   —Brian W. Kernighan and PJ Plaugher 

代码中的大量注释看起来就像上面的图片一样，令人分心。

评论是谎言
大多数时候，注释与代码不同步，没有人关心它，因此没有人维护它。

代码重构
代码在不断改进，它不断变化，发展和消亡，但代码注释只是粘滞而成为孤立的。

错误的代码有更多注释
一旦编写了难以理解的代码，我们便尝试通过注释来解释它，这充分说明了我们编写表达性代码失败的原因。

嘈杂的评论
让我们看一下公共领域中的一些代码和注释。

https://github.com/apache/hadoop/blob/trunk/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsAdmin.java

/**
   * Create a new HdfsAdmin client.
   *
   * @param uri the unique URI of the HDFS file system to administer
   * @param conf configuration
   * @throws IOException in the event the file system could not be created
   */
public HdfsAdmin(URI uri, Configuration conf) throws IOException {
FileSystem fs = FileSystem.get(uri, conf);
if (!(fs instanceof DistributedFileSystem)) {
throw new IllegalArgumentException("'" + uri + "' is not an HDFS URI.");
} else {
dfs = (DistributedFileSystem)fs;
}
}

此代码段来自流行的开源Java项目，企业中的许多注释也是如此。 这会增加噪音多于价值。

期刊评论
许多脚本代码，数据库代码，python代码都是基于此模式的，看起来团队对源代码控制不信任，他们已经接管了这一职责。 看起来像下面

/ *
2019年4月1日–最初的版本带有某人的框架代码
2019年4月10日–某人添加了配置支持 …。 … * /

标记评论
这从下面的内容开始

//开始初始化

//进行数据库调用

这在脚本编写，DB存储过程或实际的企业类型程序中也很常见。 这种模式告诉我们提取小功能是大声疾呼，但却被忽视了。

注释代码
我确定您已经看过很多次了，并且对为什么存在此无效代码感到沮丧。
看起来像这样。

//保留此备份
// fastCode（）
superFastCode（）

作者代码
IDE向添加到项目的每个文件添加注释块，如下所示

/ *
@阿什克里特
* /
作者姓名仅位于文件的顶部，但他不再维护它，并且不适用于团队或组织，但偶尔会因他的创作而受到赞誉/指责。
结论 代码注释基本上没有任何价值，它介于您和代码之间，这是一种额外的干扰。它还使年轻的程序员养成不良习惯，因为他们认为“ 添加注释可使代码更好 ”。

在某些情况下，注释在您编写公共API时很有用，但仍要谨慎编写，软件工程师很聪明，他们可以理解代码是否没有意外的复杂性。

我将给您留下Kevlin Henney另一条著名的推文

如果您喜欢该帖子，那么可以在Twitter上关注我 。

翻译自: https://www.javacodegeeks.com/2019/11/dont-comment-bad-code-rewrite-it.html

php 代码需要重写注释