关闭

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

2013年4月19日,星期五

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

与任何工作一样,程序员应该始终努力提高他们的工作质量. 在编程, 我们可以使用许多结构松散的“最佳实践”技术来编写尽可能高效且易于更新和维护的代码.

有些是众所周知的, 广泛应用的最佳实践, 比如DRY(不要重复自己), 可重用的概念适用于更具体的情况, 比如设计模式. 其他是架构概念,如MVC(模型-视图-控制器). 在任何情况下,关键是要知道什么时候使用一种技术,走多远,什么时候避免它. 在这个博客中, 我想讨论自文档化代码, 哪种做法更倾向于明确的变量名和函数名, 以及其他编码实践,使代码易于理解, 过度评论.

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

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

这可以更清楚一些. 变量名应该反映它们的用途. 这段代码还应该被做成一个具有描述性名称的函数.

int findLowestInt(int[] numbers) {
  int lowestInt = numbers[0];
  For (int迭代器:numbers) {
    if(iterator < lowestInt) {
      lowestInt =迭代器;
    }
  }
  返回lowestInt;
}

这样好多了. 即使在这个非常简单的示例中,代码也变得更容易理解. 将完成单个任务的代码块分解为各自的函数还可以使代码更加模块化和易于理解. 当然在某些语言中, 调用函数会引起开销, 所以在这种情况下,你应该明智地权衡你的选择.

自记录并不意味着完全无注释. 在许多情况下仍然需要注释. 自文档化代码是九游会客户端app避免 不必要的 通过生成尽可能清晰的代码来注释. 不幸的是, 有些人接受了这个想法,并且做得有点过头了, 只是作为一个借口,完全不评论. 该理论的批评者通常会反对这种极端的实施, 而不是鼓励在多个层次上进行更好编码的核心概念. 而且,这实际上只适用于源代码. 也就是说, 如果你正在构建一个库或API或任何外部使用的东西, 为使用该产品的用户提供的文档, 而不是编辑代码, 仍然像以前一样重要吗. 如果这意味着包括将由Javadoc或其他文档生成器处理的结构化注释, 那就这样吧.

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

当你认真考虑的时候, 自文档化代码甚至不是九游会客户端app注释的缺失或减少. 真正的重点是使代码尽可能的干净和清晰, 其中包括删除冗余地解释代码明显在做什么的注释. 当然,这只有在代码的功能很明显的情况下才有效,这才是真正的关键. 此外,带有过多注释的糟糕代码仍然是糟糕代码. 相反, 在创建代码时尽量减少注释的使用, 结果是代码更简洁, 更高效的, 更具可维护性和模块化.

九游会客户端app九游会客户端

九游会客户端是一家提供全方位服务的创意B2B机构,拥有数十年执行客户愿景的经验. 该获奖公司专门从事 网页设计, 标志设计、 品牌, 营销活动, 打印, UI / UX, 视频制作, 商业摄影, 广告,以及更多. 九游会客户端秉承个人追求卓越的最高标准,由于其多元文化背景,可以从独特的角度看待事物.  该公司始终如一地提供定制服务, 高质量的, 运用技术悟性和无穷的创造力为客户提供创新的解决方案. 更多信息,请访问 MatchaDesign.com.

相关标签

你可能还会喜欢