10 Tips for Writing Better Code （阅读理解）

Posted 2020-10-05 LightSong@计海拾贝

出发点

http://www.tuicool.com/articles/A7VrE33

阅读中文版本《编写质优代码的十个技巧》，对于我编码十年的经验，也有相同感受，

太多的坑趟过，太多的经历走过，对良好编码的技巧，只能说更加心有灵犀。

下面从英文原版阅读，结合自己的理解，尝试注解下作者的观点。

 注解 -- 原文见下网址

https://cdiggins.github.io/blog/programming-tips.html

10 Tips for Writing Better Code

注：翻译成编写更好代码的十个技巧，不如翻译成质量优良代码的十个技巧，更好合适。

30+ years experience trying to write better software distilled down into 10 best practices.

注：30多年努力编写质量优良软件的经验， 被提炼为10个最佳实践。为工匠精神点赞， 中国的程序员不用担心30岁以后要失业，看看人家干了30年了。

1. Follow the Single Responsibility Principle

Functions are the single most important form of abstraction in a programmer‘s arsenal. The more they can be reused the less code you have to write, and the more reliable they become. Smaller functions that follow the Single responsibility principle are more likely to be resued

注：一件函数只做一件事情， 此精神类似unix设计哲学， 极简而奢。 函数是程序的细胞， 每一个细胞是可复用的， 健康度良好的， 则使用函数组织起来软件，必然是健壮的， 并且更好维护， 更快地组建新的软件。

 

2. Minimize Shared State

You should minimize implicit shared state between functions, whether it is a file scoped variable or object‘s member fields, in favor of explicitly required values as arguments. Code becomes a lot easier to understand and reuse when it explicit what that function requires to produce the desired results.

A corrollary to this is that you should prefer static stateless variables to member variables on an object.

注： 共享状态本身就不应该存在， 不应该在不同的函数之前共享同一个变量， 特别是变量是全局变量，造成程序逻辑不清晰， 容易走到异常情况。

如果必须要有共享状态， 则必须使用函数入参的形式， 显示声明，函数依赖的变量， 不要去引用全局变量。

这种思想， 是函数式编程的思想， 对于纯函数， 即给定函数的输入， 函数的输出在任何情况下都是固定的， 可预期，不用担心依赖全局变量，产生的不可控制性。

函数式编程，典型代表语言有 haskell， js中有facebook出品的 immutablejs（https://github.com/facebook/immutable-js）， 也是为了达到这种效果。

 

3. Localize Side Effects

Ideally side-effects (e.g. printing to console, logging, changing global state, file-system manipulations, etc.) should be placed in separate modules, and not scattered throughout the code. Often side-effects in functions are violating the single responsibility principle.

注： 局部化副作用， 对于存在副作用， 例如函数的执行， 改变的全局变量， 则尽量将副作用局部化， 例如局部化到模块， 不要让副作用散落在程序的任何地方。

即减少副作用的影响范围。

 

4. Prefer Immutable Objects

If an object‘s state is set once in its constructor and never changed again it become much easier to debug since it remains valid once it is constructed correctly. This is one of the easiest ways to reduce complexity in a software project.

注： 优选不可变对象。 对象的属性在程序运行过程中， 不被改变， 更加易于调试。 例如 array.map 接口设计， array.map（v=v+1）， 此操作不改变array对象本身， map函数会产生一个新的 array，并返回。

 

5. Interfaces over Classes

Functions that accept an interface (or a template argument or concept in the case of C++) are more reusable than functions that operate on a class.

注： 函数接受接口， 更加具有复用性， 相比较函数接受 类。

面向接口的编程， 比面向类的编程， 更加具有灵活性。

一： 如果函数依赖与类， 则函数只能服务于此类， 和此类的子类。 如果依赖接口， 则函数可以服务于任何实现了此接口的任何对象。

二：如果函数依赖类， 函数依赖的对象变大， 实际其只需要依赖 接口， 容易在函数中 产生副作用， 调用了类的其它非接口的公共函数和属性。

 

6. Apply Good Principles to Modules

Look for opportunties to break up a software project into smaller modules (e.g. libraries and applications) to encourage module level reuse. Some key principles to follow for modules are:

1. Minmize dependencies
2. Each project should have a single well defined responsibility
3. Don‘t repeat yourself

You should strive to keep your project small and well-defined.

注： 寻找机会分解软件项目为更小的模块， 例如库和应用， 这是为了鼓励 模块级别重用。一些关键的原则：1、 极小化模块之间的依赖， 2、每个模块有一个单一的定义良好的职责， 3、不要重复。

软件开发， 一个关键的环节就是设计， 设计就是要把整个系统 拆分为不同的子模块， 这样减少软件开发的复杂度，即使的复杂度处于可控范围内。 模块与模块之间的链接尽量小，并且明确， 符合 “高内聚、低耦合”原则。

 

7. Avoid Inheritance

In object-oriented programming, inheritance, especially with virtual functions tends to be a dead-end in terms of reusability. I have had very little success writing or working with libraries that encourage overriding classes.

注： 避免继承。 继承减少的服用性， 继承之后， 必然有一些函数或者属性， 是需要覆盖父亲类的， 或者新增父亲类没有的函数和属性。

如果一个对象， 其划分的比较合理， 职责比较单一， 则对象的所有属性和函数是一套整体的内容， 子类的函数覆盖， 或者新增， 很容易就割裂了对象的整体性，

一部分逻辑在父亲， 一部分逻辑在儿子， 实际上造成了逻辑的低耦合。

 

8. Test as you Design and Develop

I am not a hard-core advocate of test-driven development but writing tests as you go leads to code that naturally follows many of the guidelines. It also helps reveal n error earlier. Avoid writing useless tests though, good coding practices mean that higher level tests (e.g. integration tests or feature tests over unit tests) are much more effective at revealing defects.

注：当你开发过程中， 写测试， 有助于发现低水平的缺陷， 进而促进集成测试和功能测试， 更加有效地发现缺陷。

 

9. Prefer Standard Libraries to Hand-Rolled Ones

I can‘t tell you how often I have seen a better version of std::vector or std::string, but it almost invariably a waste of time and effort. Apart from the obvious fact that you are introducing a new place for bugs (see Tip #10), other programmers are far less likely to reuse your code as opposed to something that is widely understood, supported, and tested.

注： 优选标准库， 不要手工制造了。 自己造轮子， 则多出一个产生bug的口子， 使用标准库， 则不容易出现bug， 因为标准库已经被官方测试发布过， 更加质量优良， 且有bug， 也很快被修复。自己造， 一则浪费时间， 二则容易引入bug。

 

10. Avoid Writing New Code

This is the most important tip that every programmer should follow: the best code is the code that isn‘t written. The more lines of code you have, the more defects you will have, and the harder it is to find and fix bugs.

Before writing a line of code ask yourself, is there a tool, function, or library that already does what you need? Do you really need that function as opposed to calling another one that already exists?

注： 最好的代码就是自己不写代码。 以无招胜有招， 达到武学最高境界。  不说啥了，尽量不要自己造轮子， 使用别人造的轮子。 如果真想造， 就参加开源项目， 为开源事业贡献力量。

 

 

Final Words

I have found that programming is a skill very similar to learning an art form or a sport, you get better at it through mindful practice, and by learning from others. Continuously working to improve the quality of the code you produce will help you become a more effective programmer.

持续改进你的代码， 会帮助你称为一个更加高效的程序员。

 

致敬30年的老兵！！