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

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

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

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

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

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