自文档化代码:清洁代码的最佳实践

日博体育app下载- 2013年4月19日星期五

与任何工作一样,程序员应该始终努力提高工作质量. 在编程, 我们可以使用许多松散结构的“最佳实践”技术来编写尽可能高效、易于更新和维护的代码. 有些是众所周知的, 具有广泛深远影响的最佳实践, 比如DRY(不要重复自己), 可重用的概念适用于更具体的情况, 像设计模式. 其他的是架构概念,如MVC(模型-视图-控制器). 在任何情况下,关键是要知道什么时候使用一种技术,走多远以及什么时候避免使用它. 在这篇博客, 我想讨论自我文档化的代码, 哪一种习惯倾向于使用清晰的变量名和函数名, 以及其他使代码易于理解的编码实践, 在过多的评论.

matcha-design-self-documenting-code-best-实践-for-cleaner-code.jpg

为了说明我的观点,让我们看一个例子. 这是一个代码块,它在一个整数数组中找到最小值. 我是用Java写的,但是将它转换成任何类似的结构化语言应该很简单.

Int l = Int [0];
For (int I: int) {
  if(i < l) {
    l = i;
  }
}

这可以清楚得多. 变量名应该反映它们的用途. 这段代码也应该被制作成具有描述性名称的函数.

int findlowastint (int[] numbers){/ /使用最小值
  = [0];
  For (int iterator: numbers) {
    if(iterator < lowestInt) {
      lowestInt =迭代器;
    }
  }
  返回lowestInt;
}

这是更好的. 即使在这个非常简单的示例中,代码也变得更容易理解. 将完成单个任务的代码块分解成它们自己的函数,还可以使代码更模块化和更易消化. 当然在某些语言中, 调用函数会产生开销, 所以在这些情况下,你应该明智地权衡自己的选择.

自我文档化并不意味着完全不需要注释. 在很多情况下仍然需要注释. 自我文档化的代码是日博体育app避免 不必要的 通过生成尽可能清晰的代码来注释. 不幸的是, 有些人采纳了这个想法,并且做得有点过头了, 简单地作为一个借口,完全省略评论. 该理论的批评者通常反对这种极端的实践, 而不是鼓励在多个层面上进行更好的编码的核心概念. 此外,这实际上只适用于源代码. 也就是说, 如果你正在构建一个库或API或任何外部使用的东西, 为使用产品的用户提供的文档, 而不是编辑代码, 仍然和以前一样重要吗. 如果这意味着包含将由Javadoc或其他文档生成器处理的结构化注释, 所以要它.

我所见过的支持评论的最大论点是解释 为什么 比如为什么选择了一个特定的算法而不是另一个同样可以完成这项工作的算法. 我不认为在任何情况下这都是必要的, 但是,如果有不明显的理由使用一种特殊的方法,否则可能会显得较差, 将这些信息提供给那些以后可能会处理代码的人是很有用的. 例如,如果选择一个较慢的方法是因为它是线程安全的或更安全的.

当你认真去做的时候, 自我文档化的代码甚至与注释的缺失或减少无关. 真正的要点是让代码尽可能的干净和清晰, 这包括删除多余的注释,解释代码显然在做什么. 当然,这只有在代码的作用是显而易见的情况下才有效,这才是真正的重点. 此外,带有大量注释的糟糕代码仍然是糟糕的代码. 相反, 在努力以一种几乎不需要注释的方式创建代码时, 结果是代码更简洁, 更高效的, 更易于维护,更模块化.

了解 日博体育app下载.

日博体育app下载
日博体育app下载是一家全方位服务的创意机构 网页设计打印身份品牌界面设计视频制作静止摄影 和 运动设计. 利用我们对卓越的热情,多元文化背景,和 获奖 实践, 我们始终如一地提供高品质的, 自定义, 创新的解决方案,以满足日博体育app多样化的市场需求. 欲了解更多信息,请访问 www.MatchaDesign.com.