微信号:Ituuz_coder

介绍:技术分享、经验总结以及生活学习心得.

快读《代码大全2》之:定制编程规范

2017-07-16 00:00 ituuz

布局与风格

31.1 布局与风格的基本原则

  • 格式化的基本原理指出,好的布局凸显程序的逻辑结构。

  • 傻子都会写让计算机理解的代码;而优秀的程序员写的是人能看懂的代码。

  • 好的布局方案的关键是能使程序的外观与逻辑结构相符。

  • 编程工作量的一小部分是写让机器读的程序,大部分工作是写能让他人看懂的程序。

  • 良好布局的目标:

    • 准确表现代码的逻辑结构。

    • 始终如一地表现代码的逻辑结构。

    • 改善可读性。

    • 经得起修改。

31.2 布局技术

  • 空白能够增强可读性。空白包括空格、制表符、换行、空行,是展现程序风格和结构的主要手段。

  • 代码分组:思路以段落分组,段落间用空行分割。

  • 缩进:请用缩进形式显示程序的逻辑结构。

  • 括号:或许有些括号并非必要,但它们能使语义更加清晰,看看下面不加括号的例子:

//能一眼看出计算的优先级么?
var sum = 12 + 4 % 3 * 7 - 8 + 6 >> 1;

31.5 单条语句的布局

  • 用空格会让表达式更易读。

  • 较长语句续行的时候要明显。断句最简单的方法是将第一行部分做成若其单独时就有明显语法错误的样子。

  • 把紧密关联的元素放在一起。

  • 不要将赋值语句按等号对齐。当变量名改变或者几行移动到其他位置的时候,要维持对齐就很麻烦,增加了维护成本。

  • 每行仅写一条语句:

    • 在编译器指出某行有错误时可以更容易找到错误。如果一行有多条语句,行号并不能告诉你哪个语句有错误。

    • 在基于行进行调试的IDE中更容易进行调试。

    • 开发编辑成本更低。删除一行或者临时要将某行注释时更方便。

  • 每行只声明一个数据。

  • 变量的声明应尽量接近其首次使用的位置。

  • 合理组织声明的顺序。比较好的建议是按照功能逻辑分块。

31.6 注释的布局

  • 注释做的好可大大增进程序的可读性,而糟糕的注释却会帮倒忙。

  • 注释的缩进要与相应的代码缩进一致。

  • 每行注释要与上一块代码块用空行分割,让逻辑更清晰。

31.8 类的布局

  • 如果文件包含多个类,在文件头和多个类之间要有清楚的注释标注。

  • 一个文件建议只有一个类,这个不绝对,个别时候是可以这么做的,比如一个类只在这个文件中的另一个类使用,逻辑上是内嵌的,这样就是合理的。但是一个文件只有一个类总是没错的。

  • 文件命名应当与类名相关。


32 自说明代码

32.1 外部文档

  • 外部文档是指脱离代码的相关文档。很多成熟的项目都有大量的外部文档,比如程序架构相关文档、框架使用说明、单元测试等。

32.2 编程风格做文档

  • 在代码层文档中起到主要作用的因素并非注释,而是良好的编程风格。编程风格包括良好的程序结构、简单易懂的方法、有意义的变量名、类名和常量、清晰的布局,以及最低复杂度的控制流及数据结构。

32.4 高效注释之关键

  • 注释的作用及种类

    • 解释代码:解释性注释通常用于解释复杂、有巧、敏感的代码块。

    • 代码标记:有时程序员需要一些注释去标记未完成或未完善的代码,但在发布后这些注释一定要删除。

    • 概述代码:概述性注释是将若干行代码的意思以一两句话表达出来。

    • 代码意图说明:目的性的注释来指明一段代码的意图。他指出要解决的问题,而非解决方法。

    • 传达代码无法表达的信息:包括版权声明、版本记录等。

  • 高效注释

    • 用伪代码说明去减少注释时间。写代码时就以注释勾勒框架会让你的逻辑更清晰和更高效。

    • 写易于维护和修改的注释,下面这种就不易于维护修改,每次修改注释内容左右两边的星号都要重新对齐:

    • 将注释集成到你的开发风格中去,等项目结束时再写注释就太晚了。

    • 写易于维护和修改的注释,下面这种就不易于维护修改,每次修改注释内容左右两边的星号都要重新对齐:

32.5 注释技术

  • 对于好的代码,很少需要对单行代码进行注释,当需要注释的时候,一般都是下面两种情况:

    • 该行代码太复杂,因而需要注释。

    • 该行语句出过问题,标注一下。

  • 不要对单行语句进行行尾注释,看起来很不整洁和明了。适合行尾注释的只有成员变量的声明,在使用这些注释的时候注意要风格统一。

  • 代码本身应尽力做好说明。

  • 注释代码段时应该注重为什么这么做,而不是说明怎么做的。很多人写的注释都是怎么做的,就变成了对代码的翻译。正常良好的代码是不用双语翻译的。

  • 说明非常规做法:假如代码中可能含义表达的有歧义,不明显,就把含义放在注释里。比如你用了拐弯抹角的方法以获得性能的提升,就要注释为什么这么做,及做了之后有那些好处。

  • 为违背良好编程风格的地方注释。解释必须违背的原因。

  • 类注释的一般原则:

    • 说明该类的设计方法。说明类的设计思路和总体设计等。

    • 说明用法和局限性。

    • 注释类接口,但不要在类接口出说明实现细节。

32 要点总结

  • 该不该注释是个需要认真思考的问题。差的注释只会浪费时间,帮倒忙。好的注释才有价值。

  • 源代码应当含有程序大部分的关键信息。只要程序依然在用,源代码比其它资料都能保持正确。

  • 好的代码本身就是最好的说明。如果代码太糟糕,需要大量的注释,应当先试着改进代码,直至无需过多的注释为止。

  • 注释应说明代码无法说明的东西,例如概述或用意等。

  • 有的注释风格需要许多重复性劳动,改用易于维护的注释风格。


如果对文章感兴趣,欢迎关注我的公众号


 
代码与画家 更多文章 快读《代码大全2》之:前期架构 项目前期准备的重要性 Trello-看板管理 JavaScript性能优化总结 《至少还有你》- 游戏从业者的妻子版
猜您喜欢 揭秘浏览器远程调试技术 2015 GOOGLE I/O大会看点总结:新产品新工具新计划 从Swift看Objective-C的数组使用 站在众人肩膀上做测试 浅析weex之vdom渲染