【译】Good code Vs Bad code

• 原文地址: Good code Vs Bad code
• 原文做者: Navdeep Singh
• 译者: Chris xiong

在写任何一门语言的时候，它们都有好的代码实践和很差的代码实践。这两种代码可能都能编译运行。可是很差的代码可能会在开发，调试和修改中引发一些问题。在工做团队中，不管你的程序运行情况如何，某些人总要阅读而且修改你代码的某些地方。他们可能会添加一些新属性，修改一些bug,或者只是想明白它们是如何工做的。一样的，你也会须要去读其余人的代码作一样的事情。若是代码可读而且容易理解，每一个人都会更舒服一些。

高质量代码的重要性:要明白高质量代码的重要性，首先咱们要去明白低质量的代码可能会致使什么问题：编写的代码可能会致使财务损失或者在进一步维护，改进或调整软件时浪费更多的时间。
你可能会在某个时间写了你的代码，而后在很长时间后再来维护它。所以给你的程序写文档和命名约定都变得很是重要。
不少时候，我会听到个人同事开玩笑说他们怎么不记得他们几天前刚写的代码或逻辑。当你把代码写成很差的风格后，你就会花更多的时间来回忆你到底作了什么？当一个艺术家不了解它们的做品时，事情就会开始变得失控。
当写代码时脑海中必定要记住的几件事情
代码注释:大多数现代语言都有声明式的文档注释，用单行和多行注释结合来使得代码更易懂和维护。好的代码注释应该是解释为何这些事情要被作而不是告诉别人作了什么事情。代码自己应该要能告诉别人作了什么。对注释的须要应该是最小的。

缩进：好的代码结构如图所示（标准4个空格缩进），对于尝试明白这些代码的人来讲，能明显看到哪块代码开始，哪块代码结束，能让他们更加清楚直接的跟随代码的逻辑。

Readme:当你面前有一个项目代码，可是你设置而且第一次运行要花费你几个小时才能对这个项目明白个大体，这是很是烦人的。若是这里有个readme文档，这就显得颇有帮助了。在访问代码以前，先对项目进行一个简短的介绍老是比较好的，一个正确结构化的Readme就是这样作的。一个结构化的Readme文档就像这样

项目名(Project Title)

这里写一段项目描述

开始项目(Getting Started)

这些说明将为您提供在本地机器上运行的项目副本，以用于开发和测试，有关如何在实时系统上部署项目的说明，请参阅部署。

先决条件(Prerequisites)

为了安装这个软件你须要去作什么事情，而且怎么安装

给一个例子

安装(installing)

一步步告诉你怎么获得一个运行开发环境

步骤以下：

给例子

而且重复

直到结束

以一个从系统中获取一些数据或使用它进行一些演示的小例子结束。

进行测试（running test)

如何对这个项目进行自动测试

分解成端对端测试

解释一下这些测试都是什么而且为何这么测试

give an exmaple

代码分割测试

解释一下这些测试都是什么而且为何这么测试

give an exmaple

部署 Deployment

关于如何在实时系统上部署的一些其余说明

构建 Build

• xxx -使用的web框架
• xxx -依赖管理
• xxx -用来生成rss源

贡献 Contributing

请参阅CONTRIBUTING.md，了解咱们的行为准则以及向咱们提交请求（PR）的过程。

版本 Version

咱们使用SemVer进行版本控制。 有关可用的版本，请参阅此存储库上的标签。

做者 Authors

• chris xiong - 初始化工做

另见参与此项目的贡献者名单。

许可证 License

该项目根据MIT许可证得到许可 - 有关详细信息，请参阅LICENSE.md文件

告知 Acknowledgments

• 给任何使用代码的人一些提示
• 灵感
• 等等

规范化命名:咱们常常会碰到命名为apiManager的类。当咱们看到这种类名的时候，实际上咱们是不清楚这个类的实际用途的。根据最佳编码实践规范，咱们的类应该遵循单一功能原则，恰当的规范化命名结合单一功能原则可让咱们在跟踪一个项目时变得容易。若是类正在执行一些密集的工做单元，以便经过查看代码块来区分变量的什么时候何地超出做用域，则不一样做用域的命名规范也会有所不一样。
避免魔法数字:一个彻底未被声明的常量，这个值是程序能正常工做的特定值。没有其余人能知道为何选择这个数字，它最神奇的地方时，没有人真正知道这个魔法数字是怎么样影响程序运行的。
魔法数字是邪恶的，咱们不该该使用它。

调整项目时间：上面的图片说明了问题。

为了编写质量代码（整洁的代码），应该使用的一些常见作法及其相对重要性以下图

写高质量的代码是一个浩大的过程。当你尝试去写高质量代码时,一些须要去考虑的点以下：

• 好的代码是组织良好的。类中的数据和函数是合在一块儿的，类之间没有一些无关的依赖关系。它看起来不像是“意大利面”
• 好的代码是很好测试的。测试用做代码的可执行规范和其使用示例。
• 好的代码不须要过多奇淫技巧。它以简单明了的方式作事情。
• 好的代码是以小块，易于阅读的小单元进行开发的。这些单元在代码开发过程当中可以被复用。

感谢阅读，若是你认为它是有用的请分享:）