这篇文章真是一级棒,介绍了在java里如何规范地命名,以便更好地控制代码的质量。规范的东西总要学,它能给我们带来惊喜。
个人不同意常常写注释,除了版权注释,其余最好一行注释都不写。之所以要写注释,只能说明你的代码不够完美。
Java Bean
1. 注释规范
定义这个规范的目的是让项目中所有的文档都看起来像一个人写的,增加可读性,减少项目组中因为换人而带来的损失。(这些规范并不是一定要绝对遵守,但是一定要让程序有良好的可读性) Java 的语法与 C++ 及为相似,那么,你知道 Java 的注释有几种吗?是两种? // 注释一行 /* ...... */ 注释若干行 不完全对,除了以上两种之外,还有第三种,文档注释: /** ...... */ 注释若干行,并写入 javadoc 文档.
1. 注释要简单明了。
String userName = null; //用户名
2. 边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
3. 在必要的地方注释,注释量要适中。注释的内容要清楚、明了,含义准确,防止注释二义性。保持注释与其描述的代码相邻,即注释的就近原则。
4. 对代码的注释应放在其上方相邻位置,不可放在下面。对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释应放在此域的右方;
5. 同一结构中不同域的注释要对齐。
6. 变量、常量的注释应放在其上方相邻位置或右方。
7. 全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
8. 在每个源文件的头部要有必要的注释信息,包括:文件名;版本号;作者;生成日期;模块功能描述(如功能、主要算法、内部各部分之间的关系、该文件与其它文件关系等);主要函数或过程清单及本文件历史修改记录等。
/** * <p>Project: 项目名称</p> * * <p>Description: 类功能描述</p> * * <p>date 创建的修改的日期</p> * * <p>Copyright: Copyright (c) 2006 VCOM</p> * * @author: * @version 5.0 **/ |
9. 在每个函数或过程的前面要有必要的注释信息,包括:函数或过程名称;功能描述;输入、输出及返回值说明;调用关系及被调用关系说明等
/** * Description :checkout 提款 * @param Hashtable cart info * @param OrderBean order info * @return String */ public String checkout(Hashtable htCart, OrderBean orderBean) throws Exception{ } |
10. javadoc注释标签语法
@author 对类的说明 标明开发该类模块的作者
@version 对类的说明 标明该类模块的版本
@see 对类、属性、方法的说明 参考转向,也就是相关主题
@param 对方法的说明 对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说明
2. 命名规范
1. Package 的命名
Package 的名字应该都是由一个小写单词组成。
package com.neu.util
2. Class 的命名
Class 的名字必须由大写字母开头而其他字母都小写的单词组成 ,对于所有标识符,其中包含的所有单词都应紧靠在一起,而且大写中间单词的首字母。
public class ThisAClassName{
}
3.Class 变量的命名
变量的名字必须用一个小写字母开头。后面的单词用大写字母开头
userName , thisAClassMethod
4.Static Final 变量的命名
static Final 变量的名字应该都大写,并且指出完整含义。
/**
*DBConfig PATH
**/
public static final String
DB_CONFIG_FILE_PATH ="com.neu.etrain.dbconfig";
5. 参数的命名
参数的名字必须和变量的命名规范一致。
6. 数组的命名
数组应该总是用下面的方式来命名:
byte[] buffer;
而不是:
byte buffer[];
7. 方法的命名
方法的名字,首字母都要小写。
setCounter(int size){
this.size = size;
}
3. Java文件规范
所有的 Java(*.java) 文件都必须遵守如下的样式规则
1. 版权信息
版权信息必须在 java 文件的开头,比如:
/** * Copyright ? 2000 Shanghai XXX Co. Ltd. * All right reserved. */ |
其他不需要出现在 javadoc 的信息也可以包含在这里。
2. Package/Imports
package 行要在 import 行之前,import 中标准的包名要在本地的包名之前,而且按照字母顺序排列。如果 import 行中包含了同一个包中的不同子目录,则应该用 * 来处理。
package hotlava.net.stats;
import java.io.*; import java.util.Observable; import hotlava.util.Application; |
这里 java.io.* 使用来代替InputStream and OutputStream 的。
3. Class
接下来的是类的注释,一般是用来解释类的。
/** * A class representing a set of packet and byte counters * It is observable to allow it to be watched, but only * reports changes when the current set is complete */
|
接下来是类定义,包含了在不同的行的 extends 和 implements
public class CounterSet extends Observable implements Cloneable |
4. Class Fields
接下来是类的成员变量:
/** * Packet counters */ protected int[] packets; |
public 的成员变量必须生成文档(JavaDoc)。proceted、private和 package 定义的成员变量如果名字含义明确的话,可以没有注释。
5. 存取方法
接下来是类变量的存取的方法。它只是简单的用来将类的变量赋值获取值的话,可以简单的写在一行上。
/** * Get the counters * @return an array containing the statistical data. This array has been * freshly allocated and can be modified by the caller. */ public int[] getPackets() { return copyArray(packets, offset); } public int[] getBytes() { return copyArray(bytes, offset); }
public int[] getPackets() { return packets; } public void setPackets(int[] packets) { this.packets = packets; } |
|
6. 构造函数
接下来是构造函数,它应该用递增的方式写(比如:参数多的写在后面)。
访问类型 ("public", "private" 等.) 和 任何 "static", "final" 或 "synchronized" 应该在一行中,并且方法和参数另写一行,这样可以使方法和参数更易读。
Public CounterSet(int size){ this.size = size; } |
7. 克隆方法
如果这个类是可以被克隆的,那么下一步就是 clone 方法:
Public Object clone() { try { CounterSet obj = (CounterSet)super.clone(); obj.packets = (int[])packets.clone(); obj.size = size; return obj; }catch(CloneNotSupportedException e) { throw new InternalError("Unexpected CloneNotSUpportedException: " + e.getMessage()); } } |
|
8. 类方法
/** * Set the packet counters * (such as when restoring from a database) */ protected final void setArray(int[] r1, int[] r2, int[] r3, int[] r4) throws IllegalArgumentException { // // Ensure the arrays are of equal size // if (r1.length != r2.length || r1.length != r3.length || r1.length != r4.length) throw new IllegalArgumentException("Arrays must be of the same size"); System.arraycopy(r1, 0, r3, 0, r1.length); System.arraycopy(r2, 0, r4, 0, r1.length); }
|
9. toString 方法
无论如何,每一个类都应该定义 toString 方法:
Public String toString() { String retval = "CounterSet: "; for (int i = 0; i < data.length(); i++) { retval += data.bytes.toString(); retval += data.packets.toString(); } return retval; } } |
10. main 方法
如果main(String[]) 方法已经定义了, 那么它应该写在类的底部。
JSP部分
1. jsp/html命名规范
jsp与html文件名全部小写,并遵循如下的规范:
u 数据/内容显示页
名词,多个单词用下划线分隔,要求能说明显示内容的信息,采用名词+”_”+操作或者类型 ,为避免冲突,可加上 “_list”。例如:
user_edit.jsp,user_list.jsp,user_index.jsp
u 操作处理页
命名格式:名词_下划线_动词,例如:file_delete.jsp。
u 含frame页面
<frameset>中<frame>的name属性命名的格式是①xxx._②xxx_③xxx
①xxx部分用来标识当前页面隶属于整个系统中的哪一功能模块。
如:属于ebwebmail则被表示为ebwebmail,其它情况依次类推。
②xxx部分标识当前页面所要完成的功能。
如:完成用户登录的功能则被标识为login,其它情况依次类推。
③xxx部分用来用来表示页面在浏览器窗口所处的位置。
处于浏览器窗口的顶部则标识为top,其它情况依次类推。
例如:ebwebmail_inbox_top.jsp
<frame> src属性相应的文件名根据情况建议在原命名规范上用下划线加上所处窗口的位置。
u javascript脚本方法
脚本函数都以①xxx_②xxx的方式命名。
①xxx对应页面隶属的模块。
②xxx表示函数所要实现的功能(动宾结构),多个单词用下划线连接。
例如:ebwebmail_send_mail()
模块通用的脚本函数必须集合于一个js文件中,在页面上通过<script language=”javascript” src=”url”></script>形式导入。js文件名命名使用模块名,例如:ebwebmail.js。
如果项目已经提供了公共js脚本,则优先使用公共js脚本中提供的函数。
所有定义方法的<script>元素定义在<head></head>中或</body>后。
u javascript脚本内部变量与参数
单词之间用下划线分隔且全部小写,例如:
var file_size。
u <form>表单name属性
统一以“form_”开头,其后加该表单所需收集的信息的作用或动作,例如:form_file_upload 或 form_send_mail。
u 表单elements
表单element的名称以element需收集的信息标示命名,单词之间使用下划线分隔且全部小写,例如:
<input type=”text” name=”username”>
<input type=”radio” name=”file_type”>
<textarea name=”content” rows=”5” cols=”40”>
u cookie命名
命名格式:模块名_存储信息名词(多个单词用下划线分隔) ,全部大写,例如:EBWEBMAIL_SORT_TYPE。
u window.open中name参数的命名
javascript的window.open方法中有一个name的参数,浏览器约定同样的名字的窗口只能打开一个,如果程序间名字重复将相互冲突。如果不限制打开窗口数,可以指定‘’或“”(不是null),否则需要加上模块名,例如ebwebmail_viewmail。
2. jsp/html代码规范
u jsp/html描述注释
jsp/html页面顶部必须存在一个基本描述注释,包含功能描述、参数列表和历史修改信息,例如:
<%--
/**************************************************
*
* NAME : file_download.jsp
*
* PURPOSE : 下载文件提示
*
* PARAMETERS :
* file_id - 文件ID号
* force – 是否强制下载
*
* HISTORY
*
* 2002/04/05 Hafele 创建文件
*
* 2002/06/07 tmp 增加强制下在功能
*
*************************************************/
--%>
u jsp头格式
jsp头部一般需要遵循以下格式:
<%@ page contentType="text/html;charset=gb2312" %>
<%@ page import="java.io.*" %> // jdk标准包
<%@ page import="javax.mail.*" %> // java扩展包
<%@ page import="org.apache.xml.*" %> //使用的外部库的包
<%@ page import="com.sunrise..*" %> //使用的项目的公共包
<%@ page import=" com.sunrise.applications.*" %> //使用的模块的其他包
<%@ include file="some.jsp" %> //include其他的jsp
<%
response.setHeader("Pragma","No-cache");
response.setHeader("Cache-Control","no-cache");
response.setHeader("Expires","0");
%> //一般jsp都需要防止缓存
u html格式
1. html头一般需要遵循以下格式:
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312">
<title>some title</title>
<link rel="stylesheet" href="some.css" type="text/css">
<script language="javascript">
//some javascript
</script>
</head>
注意:必须指定一个有意义的<title>,严禁出现“Untitled”或“未命名”之类的<title>。
2. 所有html标签使用小写
3. html页面一般需要设置一个背景色(一般是#FFFFFF)。
u html语法校验
所有的jsp/html页面需要能够使用DreamWeaver正确打开(即html语法正确,没有错误的标记)。
u 注释
一般不使用html注释,除非是有必要让最终用户看到的内容。对于包含JSP代码的html块,必须使用JSP注释。对于没有必要的注释,在发行版本中必须移除。
u form属于域的maxlength
对于text类型的输入域,必须根据数据库字段的长度设置相应的maxlength,例如数据库类型是VARCHAR(64),那么maxlength是32(因为中文浏览器对于中文也认为是一个字符)。
via蜗牛之家
转载不必注明Comfish