编写易读的代码

原创 2002年07月15日 09:53:00



 

成功的开发团队要求队伍中的每一位成员遵守代码重用规则,这些规定把代码的重用性推到极至同时却不会显著降低开发人员的创造力和开发效率。如果编写和使用代码的开发人员遵守共同的程序命名规范代码和代码注释要求,那么代码的重用性就会得以大大提升。这些标准的起点是系统结构级的。你的功能规范应该在类、属性的名字、函数返回值以及其他关键程序元素的定义中反映这些标准。本文将就基本的命名规则和注释提出一些可行的建议,意图帮助读者开发自己的代码重用标准。


大小写标准


在我们开始讨论各类程序要素命名的正确方式之前,先让我们定义区分元素的字符大小写的两种最常用方式,它们是:

Pascal规范—第1个字符大写,目标名中的每个单词的第1个字母也大写,比如InvoiceNumber或者PrintInvoice。其他的所有字符都小写。
Camel规范—第1个字符不大写,但目标名中的每个单词的第1个字母大写,比如,invoiceNumber。其他的所有字符都小写。
可是,采用字符大小写区分元素可能在对大小写不敏感的编程语言中引发问题。比方说,由于C#语言区分大小写,所以你可以调用私有变量employee,接着它所具有的公共属性Employee则可以被调用者所用。这些操作是完全合法的。但是,对Visual Basic来说就会产生错误,因为VB是不区分字母大小写的,以上两种元素在VB看来都是一回事。假如你在混合语言环境下工作,你只能指定某些规则要求开发人员合理利用多种语言阅读其他人开发的代码。


命名标准
假设我们采用了以上的大小写标准,现在就让我们了解一些通用程序元素的简单命名建议。


某些类设计为模拟真实世界的对象,就这些类来说,所选用的名字就应该反映真实世界的对象、具有单数名词的格式,比方Employee、 Invoice或者Timecard等。对内部类而言可以采用Pascal规范令结果类具有单数形式的名字,比如ThreadPool或者CustomColor等。类应当是单数的,这样它们的复数形式就可以代表同类的集合名,比如Employees数组等。

类的成员
采用C#以及其他大小写敏感编程语言的开发人员应当采用camel规范命名类成员的名字。这样做可以让开发者更易于区分内部变量的名字(name)和公共属性的名字(Name)。许多VB开发人员更喜欢采用匈牙利命名法为类成员起名,也就是在名字前面加上前缀表示变量的类型,比如sName就指的是string类型的Name变量。我认为,在使用VS.NET这样高级的开发环境下这样做是不必要的,因为在这种情况下系统鼠标停留在变量之上即可可自动显示变量的类型。我个人喜欢在类成员名前加上前缀:小写的字母m。这样内部变量就保存了足够的内部类信息:内部变量mName就正好代表了公共属性Name。

方法
方法应该用Pascal规范命名,同时用合理的方式说明他们的实施行为。比方说,给数据库添加雇员的方法可以命名为AddEmployee,而打印发票的方法则不妨命名为PrintInvoice。假如方法返回的是布尔值,那么方法名应该以动词开头以便用在if语句的时候其含义更明显。比如说,假如你有一个方法的功能是确定某位雇员是否符合公司401k计划的要求,那么你可以在If语句中调用IsEligible401k方法:If IsEligible401k then…

方法参数、返回值和变量
所有的方法参数、返回值和变量都应该采用Pascal规范命名,同方法名一样也应该能反映参数或者变量所代表的含义。这一点对参数方法而言特别重要,因为你在调用方法的时候智能感知(Intellisense)会返回参数名和参数类型。所有采用方法的开发人员都应该使用描述性的名字和类型,便于相互理解其含义。

控件
控件命名是开发领域一个经常引发争议的问题。虽然大多数人赞同不应该使用控件的默认名称,比如TextBox1或者Label1等等,但是,他们还反对按照变量的方式命名控件或者采用前缀表示控件的类型。我比较喜欢采用标准的三字母前缀命名窗体中控件的名字。比如说,保存姓氏和名字的文本框控件就不妨分别命名为txtLastName和txtFirstName。处理窗体数据的命令按钮则可以命名为cmdSubmit或者cmdCancel。其实,只要你能保证控件命名的一致性而且标准易于理解即可。

注释
注释代码对所有开发人员来说都是必要的。为了教授正确的注释技术,我就经常在自己的演示程序中添加注释代码。同时,为了简化注释过程,我建议开发人员首先编写注释说明他们想编写的程序。我首先会写注释说明程序中的过程、类或者其他程序要素,但对其具体工作原理不做阐述。然后我会编写一系列的注释代码描述过程的每一主要步骤或者类的元素。在编写了定义类或者说明过程的代码之后,我对各个外部变量、控件、打开的文件乃至其他过程所访问的元素文档化,对输入参数和返回值做简要说明。

如果你在使用C#开发程序,那么VS.NET环境已具有内置的工具帮助你把内部C# 注释转换为外部HTML文档。你可以在自己的文档中加上特殊的处理指示符而改变外部文档的表示方式。有关这方面的更多信息可以参考VS.NET内部帮助文件: ms-help://MS.VSCC/MS.MSDNVS/csref/html/vcoriXMLDocumentation.htm.

编写易读代码的艺术——第一章 代码应该容易让人理解

代码应该容易让人理解 在过去的5年中,我们收集了许多“丑陋代码”的例子(其中大部分是我们自己写的),然后分析到底是什么使代码变丑陋,应用什么原则/技巧能把代码变好。最终我们注意到,所有的原则...
  • zhanglt
  • zhanglt
  • 2012年03月07日 16:53
  • 678

编写易读代码的艺术——第四章 美学

一本杂志的布局包含了很多的思想。例如,段落的长度,列的宽度,文章的顺序,还有封面故事等等。一本好的杂志,可以方便的跳着看,或顺着看。                  好的源代码也应该“看得顺眼”...
  • zhanglt
  • zhanglt
  • 2012年03月23日 17:37
  • 628

如何编写github项目的README.md文件?

针对中文,演示Markdown的各种语法具体的项目效果可以参考:https://github.com/guoyunsky/Markdown-Chinese-Demo 大标题 大标题一般显示工程名,类...
  • luojie140
  • luojie140
  • 2017年02月03日 19:16
  • 412

写给所有程序员_你的逻辑可以更简洁易读吗?

1.if层次过多。举一个很有趣的例子,假如世界上只有两种烤鸭,在北京的叫做北京烤鸭,不在北京的叫做非北京烤鸭,写烂代码的程序员思路如下:如果烤鸭不在地球,它一定不是北京烤鸭; 如果烤鸭不在陆地,它一...
  • yu_duan_hun
  • yu_duan_hun
  • 2017年10月12日 15:44
  • 82

timeago.js自动将时间戳转换为更易读的时间轴

timeago.js自动将时间戳转换为更易读的时间轴演示地址:http://www.corange.cn/demo/3870/index.htmltimeago.js自动将时间戳转换为更易读的时间轴$...
  • piperzero
  • piperzero
  • 2013年05月28日 07:14
  • 1594

磁盘与目录的容量

磁盘与目录的容量 现在我们知道磁盘的整体数据是在 superblock 区块中,但是每个各别文件的容量则在 inode 当中记载的。那在文字接口底下该如何叫出这几个数据呢?底下就让我们来谈一谈这两个...
  • u013982161
  • u013982161
  • 2016年09月04日 20:15
  • 129

android 时间的处理 将毫秒转化成 几分几秒 (02:23 类似格式)

/** * 时间的处理 *  * @param time * @return */ public static String getTimeFromInt(int ...
  • u011140027
  • u011140027
  • 2013年10月20日 16:54
  • 2011

《编程精粹-Microsoft编写优质无错代码的秘诀》的摘录

第一章:假想的编译程序1.不要期待好运气会碰到错误,应该去自己主动发现错误,排除运气对程序测试的影响,主动地抓住错误每个机会2.这章作者假想了一个非常智能的编译器,可以通过修改一些C语言规则,进行函数...
  • linux_coder
  • linux_coder
  • 2007年06月06日 15:09
  • 1297

《编写可读代码的艺术》读书笔记(二)

第一部分介绍了“表面层次的改进”,一次一行,在没有很大风险也不需要花很大代价的情况下改进代码的可读性。接下来,第二部分将讨论“简化循环和逻辑”这个主题,相对第一部分,第二部分的技巧方法通常都需要对代码...
  • e5Max
  • e5Max
  • 2013年10月03日 23:14
  • 2132

代码不朽——编写可维护软件的十大要则

“上医治未病,中医治欲病,下医治已病。” ——源自《黄帝内经》 软件是当今信息社会的 DNA。DNA 虽然小到肉眼无法察觉,它却决定着世界的一切。同样,软件虽然无形且深奥莫测,它却主宰着信息的动向。我...
  • Dennison_
  • Dennison_
  • 2017年04月02日 19:37
  • 527
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:编写易读的代码
举报原因:
原因补充:

(最多只允许输入30个字)