编写高质量的代码——从命名入手

1.用camel规则来命名类成员变量名称，即首单词（或单词缩写）小写。

2.使用描述性参数名称，参数名称应当具有最够的说明性。

3.接口定义使用Pascal规则，且必须以大写“I”开头。

4.字符串变量推荐是用“str”或“s”开头，采用string.Empty来初始化。

5.普通对象可以以“obj”开头。

6.每行语句至少占一行，如果语句过长（超过一屏），则该语句断为两行显示。

7.避免相同的代码段在多个地方出现。(尽量避免代码重复，能复用则复用)

8.SQL语句全部大写

9.html代码中所有的标签和属性应该都是小写

要写高质量的代码，不是一件容易的事，需要长年累月的锻炼，是一个量变到质变的过程，但要写好命名，只需要有比较好的英语语法基础和一种自我意识即可轻松达到。本博文将会结合本人的开发经验，总结出若干命名规则，这些命名规则纯属个人的使用习惯，不代表是一种理想的规则，在这里列举出来，供大家交流讨论。

　　1. 切忌使用没有任何意义的英语字母进行命名

for(int i=0; i<10; i++) {
    //...
}

　　这是在很多教Java基本语法的书上常见的代码片断，作为教学材料，这样写无可厚非，但作为真正的代码编写，程序员必须要养成良好的习惯，不要使用这种没有任何含义的命名方式，这里可以使用“index”。

　　2. 切忌使用拼音，甚至是拼音首字母组合

cishu =5;  // 循环的次数
zzje = 1000.00;  // 转账金额

　　笔者在做代码检查的时候，无数次遇到过这样的命名，使人哭笑不得。

　　3. 要使用英文，而且要使用准确的英语，无论是拼写还是语法

• 名词单数，必须使用单数英文，如Account、Customer。
• 对于数组，列表等对象集合的命名，必须使用复数，而且最好按照英文的语法基础知识使用准确的复数形式，如 List<Account> accounts、Set<Strategy> strategies。
• 对于boolean值的属性，很多开发人员习惯使用isXXX，如isClose（是否关闭），但这里有两点建议：1）最好不要带“is”，因为JavaBean的规范，为属性生成get/set方法的时候，会用“get/set/is”，上面的例子，生成get/set方法就会变成“getIsClose/isIsClose/getIsClose”，非常别扭；2）由于boolean值通常反映“是否”，所以准确的用法，应该是是用“形容词”，上面的例子，最终应该被改为 closed，那么get/set方法就是“getClosed/isColsed/setClosed”，非常符合英语阅读习惯。

　　4. 方法名的命名，需要使用“动宾结构短语”或“是动词+表语结构短语”

　　笔者曾看到过千奇百怪的方法命名，有些使用名词，有些甚至是“名词+动词”，而且，如果宾语是一个对象集合，还是最好使用复数。

createOrder(Order order) //good    
orderCreate(Order order) //bad
removeOrders(List<Order> orders) //good 
removeOrder(List<Order> order) //bad

　　5. 对于常见的“增删改查”方法，命名最好要谨慎

• 增加：最常见使用create和add，但最好根据英语的语义进行区分，这有助于理解，create代表创建，add代表增加。比如，要创建一个Student，用createStudent要比用addStudent好，为什么？想想如果有个类叫Clazz(班级，避开Java关键字），现在要把一个Student加入到一个Clazz，Clazz很容易就定义了一个 addStudent（Student student)的方法，那么就比较容易混淆。
• 修改：常见的有alter、update、modify，个人觉得modify最准确。
• 查询：对于获取单个对象，可以用get或load，但个人建议用get，解释请见第7点的说明；对于不分条件列举，用list；对于有条件查询，用search（最好不要用find，find在英文了强调结果，是“找到”的意思，你提供一个“查询”方法，不保证输入的条件总能“找到”结果）。
• 删除：常见的有delete和remove，但删除建议用delete，因为remove有“移除”的意思，参考Clazz的例子就可以理解，从班级移除一个学生，会用removeStudent。

　　6. 宁愿方法名冗长，也不要使用让人费解的简写

　　笔者曾经遇到一个方法，判断“支付账户是否与收款账户相同”，结果我看到一个这样的命名：

checkIsOrderingAccCollAccSame(...)

　　很难理解，我马上把它改为：

isOrderingAccountSameAsCollectionAccount(...)

　　虽然有点长，但非常容易阅读，而且这种情况总是出现得比较少。

　　7. 如果你在设计业务系统，最好不要使用技术化的术语去命名

　　笔者曾经工作的公司曾经制订这样的命名规则，接口必须要以“I”开头，数据传输对象必须以“DTO”作为后缀，数据访问对象必须以“DAO”作为后缀，领域对象必须以“DO”作为后缀。我之所以不建议这种做法，是希望设计人员从一开始就引导开发人员，要从“业务”出发考虑问题，而不要从“技术”出发。所以，接口不需要非得以“I”开头，只要其实现类以“Impl”结尾即可（注：笔者认为接口是与细节无关的，与技术无关，但实现类是实现相关的，用技术化术语无可口非）；而数据传输对象，其实无非就是保存一个对象的信息，因此可以用“**Info”，如CustomerInfo；领域对象本身就是业务的核心，所以还是以其真实名称出现，比如Account、Customer；至于“DAO”，这一个词来源于J2ee的设计模式，笔者在之前的项目使用“***Repository”命名，意味“***的仓库”，如AccountRepository，关于“Repository”这个词的命名，是来源于Eric Evans的《Domain-Driven Design》一书的仓库概念，Eric Evans对Repository的概念定义是：领域对象的概念性集合，个人认为这个命名非常的贴切，它让程序员完全从技术的思维中摆脱出来，站在业务的角度思考问题。说到这里，可能有人会反驳：像Spring、Hibernate这些优秀的框架，不是都在用“I”作为接口开头，用“DAO”来命名数据访问对象吗？没错！但千万别忽略了语义的上下文，Spring、Hibernate框架都是纯技术框架，我这里所说的场景是设计业务系统。

　　8. 成员变量不要重复类的名称

　　例如，很多人喜欢在Account对象的成员变量中使用accountId，accountNumber等命名，其实没有必要，想想成员变量不会鼓孤立的存在，你引用accountId，必须是account.accountId，用account.id已经足够清晰了。

　　“勿以善小而不为，勿以恶小而为之”、“细节决定成败”，有太多的名言告诉我们，要注重细节。一个优秀的程序员，必须要有坚实的基础，而对于命名规则这样容易掌握的基础，我们何不现行？

要点一：要名副其实。一个好的变量、函数或类的名称应该已经答复了所有的大问题。一个好名称可以大概告诉你这个名称所代表的内容，为什么会存在，做了什么事情，应该如何用等。

要点二：要避免误导。我们应该避免留下隐藏代码本意的错误线索，也应该避免使用与本意相悖的词。

要点三：尽量做有意义的区分。尽量避免使用数字系列命名（a1、a2…….aN）和没有意义的区分。

要点四：尽量使用读得出来的名称。如名称读不出来，讨论的时候会不方便且很尴尬。

要点五：尽量使用可搜索的名称。名称长短应与其作用域大小相对应，若变量或常量可能在代码中多处使用，应赋予其以便于搜索的名称。

要点六：取名不要绕弯子。取名要直白，要直截了当，明确就是王道。

要点七：类名尽量用名词。类名尽量用名词或名词短语，最好不要是动词。

要点八：方法名尽量用动词。方法名尽量用动词或动词短语。

要点九：每个概念对应一词，并一以贯之。对于那些会用到你代码的程序员，一以贯之的命名法简直就是天降福音。

要点十：通俗易懂。应尽力写出易于理解的变量名，要把代码写得让别人能一目了然，而不必让人去非常费力地去揣摩其含义。

要点十一：尽情使用解决方案领域专业术语。尽管去用那些计算机科学领域的专业术语、算法名、模式名、数学术语。

要点十二：要添加有意义的语境。需要用有良好命名的类，函数或名称空间来放置名称，给读者提供语境。若没能提供放置的地方，还可以给名称添加前缀。

学习C#之初，始终不知道怎么命名比较好，很多时候无从命名，终于有一天我整理了一份命名规范文档，自此我就是按照这个命名规范书写代码，整洁度无可言表，拙劣之处请大家斧正，愚某虚心接受，如有雷同，不胜荣幸

 C#语言开发规范

 作者ching

 

1.  命名规范

a) 类

【规则1-1】使用Pascal规则命名类名，即首字母要大写。

eg:

Class Test

{

    ...

}

【规则1-2】使用能够反映类功能的名词或名词短语命名类。

【规则1-3】不要使用“I”、“C”、“_”等特定含义前缀。

【规则1-4】自定义异常类应以Exception结尾。

eg:

Class TestException

{

    ...

}

【规则1-5】文件名要能反映类的内容，最好是和类同名。

 

b) 类字段(类成员)

【规则2-1】用camel规则来命名类成员变量名称，即首单词（或单词缩写）小写。

【规则2-2】类字段变量名前可加“_”前缀。

【规则2-3】坚决禁止在普通变量前加“m_”（这是VC老命名规则）。

eg:

Class Test

{

    privatestring myName;

    privatestring _myCoCo;

    ...

}

c）方法

   【规则3-1】方法名采用Pascal规则，第一个字符要大写。

【规则3-2】方法名应使用动词或动词短语。

【规则3-3】类中访问修饰符或功能相同的方法应该放在一起， 且公共或实现接口的方法在前。

eg:

Class Test

{

      ...

      publicvoid GetData(...)

      {

         ...

      }

 

      privatevoid GetName(...)

      {

         ...

      }

     

      privatestatic void GetCount(...)

      {

         ...

      }

 

 

}

   d）属性

      【规则4-1】使用名词定义属性，属性使用Pascal规则，首字符大写

      【规则4-2】属性和相应字段名称要关联， 可以使用“重构”菜单来生成属性。

eg:

Class Test

{

   private string myName;

   public string MyName

   {

      set

      {

         myName = Value;

      }

      get

      {

         return myName;

      }

   }

}

   e）参数

      【规则5-1】参数采用camel规则命名，且首字符小写。

      【规则5-2】使用描述性参数名称，参数名称应当具有最够的说明性。

      【规则5-3】不要给参数加匈牙利语类型表示法的前缀。

      【规则5-4】检查方法所有输入参数的有效性。

      eg:

      ClassTest

      {

         public void GetData(string name,string strFlag)

         {

            ...

         }

      }

   f）常量

      【规则6-1】只读常量使用Pascal命名规则，即首字母大写。

   【规则6-2】枚举名使用Pascal规则命名，枚举成员本质属于常量，命名规则同上。

      【规则6-3】枚举值从小到大顺序定义。

      【规则6-4】静态字段或属性采用Pascal规则，即首字符大写。

      eg:

      ClassTest

      {

         public const double Pi = 3.14159365753;

         private readonly double Pai = 3.14159365753;

      }

   g）接口

      【规则7-1】接口定义使用Pascal规则，且必须以大写“I”开头。

      【规则7-2】接口名称要有意义，中间不要有下划线“_”等字符。

   【规则7-3】如果类实现了接口，名称尽量和接口相同， 只是省掉“I”字符。

   eg:注意这里的接口修饰符只能用public和internal

   interfaceITest

   {

      ...

   }

   h）事件

      【规则8-1】委托名称采用Pascal规则，即首字符大写。

   【规则8-2】定义事件的委托要使用EventHandler后缀，且包括sender和e两个参数。

   【规则8-3】事件用到的参数，名称要带EventArgs后缀。

   eg:

   ClassTest

   {

      private delegate void DoTask();

      private event DoTask DoTaskEventHandler;

      private event DoTask DoTaskEventHandler(Object sender,EventArgse);

      private event DoTaskDoTaskEventHandler2(string   strEventArgs)

      {

         ...

      }

      ...

   }

 

i) 命名空间

【规则9-1】命名空间名称采用Pascal规则，且首字符大写。

【规则9-2】命名空间名称尽量反映其内容所提供的整体功能。

eg:

namespace MyTest

{

      ClassTest

    {

       ...

    }

    ...

}

2.  注释规范

a）文件头部注释

【规则1-1】文件都包含文件头， 要说明文件名、作者、创建时间、变更记录。

      【规则1-2】推荐采用.NET形式书写头部注释。(待考查)

   b）类及其成员注释

      【规则2-1】对方法和类使用“///”三斜线注释。

   【规则2-2】代码行文注释采用“//”和“/**/”进行，应该尽量说明问题。

3.行文规范

   a）缩写规范

      【规则1-1】标识符应当直观可望文知意，不提倡使用任何缩写。

   【规则1-2】字符串变量推荐是用“str”或“s”开头，采用string.Empty来初始化。

   【规则1-3】普通对象可以以“obj”开头。

   【规则1-4】缩写可自行定义，一般取单词的前/后字符组成，以含义直观为准则。

   【规则1-5】一般情况下不要让缩写破坏标识符的含义。

b）排版

   【规则2-1】每行语句至少占一行，如果语句过长（超过一屏），则该语句断为两行显示。

   【规则2-2】把相似的内容放在一起，比如字段、属性、方法、事件等，使用“#region--#endregion”命令分组。

   【规则2-3】多个程序元素进行对等操作时， 操作符之前、之后或者前后都要加空格。

   【规则2-4】每个方法的源程序行数原则上应该少于200行。(如果超过过多，则需要另写一方法)

   【规则2-5】语句嵌套层次不得超过3层。

   【规则2-6】避免相同的代码段在多个地方出现。(尽量避免代码重复，能复用则复用)

c）语句结构

   【规则3-1】如果使用了异常结构，一定要处理异常， 一般是要写日志文件。

   【规则3-2】分支语句不应该使用复杂长条件， 应该将长条件封装成方法。

   【规则3-3】switch语句，case后面必须接break。

   【规则3-4】禁止使用goto语句进行跳转。

   【规则3-5】行文中严禁出现“魔数”，特定含义的常数必须定义成枚举或常量。

   【规则3-6】不同类型的操作符混合使用时，使用括号给出优先级。

   【规则3-7】不允许使用复杂的操作符组合等。

   【规则3-8】循环、判断语句的程序块部分用花括号括起来， 即使只有一条语句。(return;待议)

   【规则3-9】在switch语句中总是要有default字句，建议使用断言。

   【规则3-10】每个类和方法完成单一的功能，不设计多用途面面俱到的类或方法。

   【规则3-11】严禁使用未经初始化的变量，变量通常使用构造方法来初始。

d）代码缩进

   【规则4-1】碰到大括号要换行。

   【规则4-2】不允许使用Java中的括号换行规范。

e）大小写

   【规则5-1】不要创建名称相同，但大小写区别的任何元素。

   【规则5-2】应当大写仅有两个字符的缩写。(如果只有两个字符，则都大写)

   【规则5-3】不要把易混淆的数字和字符放在一起。

   【规则5-4】使用英文命名标识符。

f）重名规范

   【规则6-1】不允许变量名、类名、属性名、 方法名等与系统标识符重名。（系统标识符见附表）

g）SQL编码规范

   【规则7-1】SQL语句全部大写。(本人的习惯是小写，为了性能，最好是大写，我自己也得把习惯改改咯，哈哈哈)

   【规则7-2】对较为复杂的SQL语句加上注释，说明其功能。

   【规则7-3】连接符OR、IN、AND、以及=、<=、>=等前后加空格。

   【规则7-4】使用明确的列代替 SELECT *。

h）软件架构

   【规则8-1】数据库中每一张表对应一个实体类/数据传输对象（DTO）。

   【规则8-2】实体类名称使用表名，也可带有Dto后缀。

   【规则8-3】三层架构应当合理使用，不应生搬硬套。

   【规则8-4】三层架构元素推荐使用后缀：

      数据传输对象         XxxxDto

      DAO工厂            XxxDAOFactory

      DAO接口            IXxxxDAO

      服务接口           IxxxxService

      DAO的数据库实现     XxxxDAOOracle/XxxxDAOInfomix

      业务逻辑           XxxxManager

i）系统

   【规则9-1】在我国内不建议随便使用设计模式等代码模式，因为并不流行。

   【规则9-2】系统输入、资源操作（如内存分配、文件及目录操作）、网络操作（如通信、调用等）、任务间的操作（如通信、调用等）时必须进行错误、超时、或则异常处理。

   【规则9-3】模块的编写应有完善的测试方面的考虑。

 

 

 

附表

表1 各种类型命名规范总结

类型	命名规则	注意事项	实例
类或结构	Pascal	首字符大写	HttpContext
接口	Pascal	加前缀I	IDataAdaper
枚举名	Pascal	首字符大写	CommandType
枚举值	Pascal	首字符大写	CommandType.Text
事件	Pascal	首字符大写	SelectedIndexChanged
自定义异常	Pascal	加后缀Exception	ArgumentException
类公共字段	Pascal	首字符大写	MaxValue(或_MaxValue)
方法	Pascal	首字符大写	ToString()
命名空间	Pascal	首字符大写	System.Xml
属性	Pascal	首字符大写	BackColor
保护或私有字段	Camel	首字符小写	myVariable
参数	Camel	首字符小写	cmdText

 

表2 数据类型缩写规则

数据类型	数据类型缩写	标准命名实例
Bool	b/is	IsVisable
Float	F	FPrice
Double	D	DPrice
Unit	U	UAge
Int	I	INumber
Char	Ch	ChCode
Byte	Bt	BtImages
String	Str	StrName
Struct	St	StStudent
Window	Wnd	WndMain
ArrayList	Lst	LstStudents
Array	Arr	ArrStudents
Hashtable	Ht	Htstudents

 

表3 Windows控件缩写规则

控件类型	控件名称	控件类型缩写	实例
Label	标签框	Lbl	LblMessage
LinkLabel	超链接标签框	Llbl	LlblToday
Button	按钮	Btn	BtnSave
TextBox	文本框	Txt	TxtName
MainMenu	菜单栏	Mmnu	MmnuFile
CheckBox	多选框	Chk	ChkStock
RadioButton	单选框	Rbtn	RbtnSelected
GroupBox	组合框	Gbx	GbxMain
PictureBox	图片框	Pic	PicImage
Panel		Pnl	PnlBody
DataGrid		Dgrd	DgrdView
ListBox		Lst	LstProducts
CheckedListBox		Clst	ClstChecked
ComboBox	组合框	Cbo	CboMenu
ListView	列表视图	Lvw	LvwBrowser
TreeView	树视图	Tvw	TvwType
TabControl		Tctl	TctlSelected
DateTimePicker		Dtp	DtpStartDate
HscrollBar		Hsb	HsbImage
VscrollBar		Vsb	VsbImage
Timer		Tmr	TmrCount
ImageList		Ilst	IlstImage
ToolBar	工具栏	Tlb	TlbManage
StatusBar	状态栏	Stb	StbFootPrint
OpenFileDialog		Odlg	OdlgFile
SaveFileDialog		Sdlg	SdlgSave
FoldBrowserDialog		Fbdlg	FbdlgBrowser
FontDialog		Fdlg	FdlgFoot
ColorDialog		Cdlg	CdlgColor
PrintDialog		Pdlg	PdlgPrint

 

 

表 4 数据库对象缩写规范

数据库对象	名称	简写	实例
Connection		Con	ConNorthwind
Command		Cmd	CmdReturnProducts
Parameter		Parm	ParmProductID
DataAdapter		Dap	DapProducts
DataReader		Dtr	DtrProducts
DataSet		Ds	DsNorthwind
DataTable		Dt	DtProduct
DataRow		Drow	DrowRow
DataColumn		Dcol	DcolProductID
DataRelation		Drl	DrlMasterDetail
DataView		Dvw	DvwFilteredProducts

 

一、HTML命名规范及格式规范

• 1、html代码中所有的标签和属性应该都是小写(虽然大写不会错,但w3建议都是小写)
• 2、在html代码中id多个单词要用下划线_连接,例如:reader_info
• 3、在html代码中clss多个单词用中划线-连接,例如:reader-info
• 4、如果仅仅是给js调用的class那么就在class的属性前加上js,例如:js-active

• 5、不管是id还是class都使用父子关系来表示(引入父节点的拼接子节点的)

  <div id="reader">
      <div id="reader_introduce" class="reader-introduce"></div>
  </div>
      
      
  1
  2
  3
      
      
  
       
       
      
      

• 6、如果元素包含子元素,那么首位就要单独占一行(常见a标签里面套img)

  <!--不推荐-->
  <ul><li>第一个</li></ul>
  <!--推荐使用-->
  <ul>
      <li>第一个</li>
  </ul>
      
      
  1
  2
  3
  4
  5
  6
      
      
  
       
       
      
      

• 7、适当的添加点注释,注释要占一行

• 8、全部使用双引号

二、关于css的命名规范及格式规范

• 1、类名关键字之间连接用中划线-拼接
• 2、为了避免class命名的重复,命名时候取父元素的class作为前缀

• 3、多个选择器生命,每一个css选择器都单独占一行

  h2,
  h3,
  h4 {
      color: #ddd;
  }
      
      
  1
  2
  3
  4
  5
      
      
  
       
       
      
      

• 4、合理的使用注释
  
  • 头部注释包括文件的版本、版本信息、作者、时间等
  • 模块注释要有开始有结束
  • 解释性注释要单独占一行

三、关于javascript的命名规范及格式规范

• 1、局部变量命名才用驼峰式命名
• 2、如果是jQuery的变量使用$为前缀
• 3、在for循环和if语句中左边的大括号应该在行的结束位置,不应该单独一行
• 4、在javascript中字符串可以使用单引号与双引号，但是建议是用单引号

• 5、合理的分号作为结束符

  • 当有换行符（包括含有换行符的多行注释）会自动加上分号
  • 当有}时，如果缺少分号，会补分号
  • 当程序源代码结束时，如果缺少分号，会补分号

• 6、如果只有一行注释就使用单行注释，多行的就使用多行注释