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、如果只有一行注释就使用单行注释,多行的就使用多行注释