扫二维码与项目经理沟通
我们在微信上24小时期待你的声音
解答本文疑问/技术咨询/运营咨询/技术建议/互联网交流
注释是为了方便自己或代码维护方更容易地读懂代码的用处。
创新互联专注为客户提供全方位的互联网综合服务，包含不限于成都网站制作、做网站、外贸营销网站建设、永和网络推广、小程序定制开发、永和网络营销、永和企业策划、永和品牌公关、搜索引擎seo、人物专访、企业宣传片、企业代运营等，从售前售中售后，我们都将竭诚为您服务，您的肯定，是我们最大的嘉奖；创新互联为所有大学生创业者提供永和建站搭建服务，24小时服务热线：13518219792，官方网址：www.cdcxhl.com
一、背景
1、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分析这段代码，我们需要什么样的注释信息？
2、怎么样避免我们的注释冗长而且凌乱不堪呢？
3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？
二、意义
程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本 , 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。
三、注释的原则
1、 注释形式统一
在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。
2、 注释的简洁
内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。
3、 注释的一致性
在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。
4、 注释的位置
保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。
5、 注释的数量
注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。
6、删除无用注释
在代码交付或部署发布之前，必须删掉临时的或无关的注释，以避免在日后的维护工作中产生混乱。
7、 复杂的注释
如果需要用注释来解释复杂的代码，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单便于使用而牺牲性能，但必须保持性能和可维护性之间的平衡。
8、 多余的注释
描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现。
9、必加的注释
典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中添加注释。为了防止问题反复出现，对错误修复和解决方法的代码使用注释，尤其是在团队环境中。
10、注释在编译代码时会被忽略，不编译到最后的可执行文件中，所以注释不
会增加可执行文件的大小。
四、JAVA注释技巧
1、空行和空白字符也是一种特殊注释。利用缩进和空行，使代码与注释容易区
别，并协调美观。
2、当代码比较长，特别是有多重嵌套时，为了使层次清晰，应当在一些段落的
结束处加注释（在闭合的右花括号后注释该闭合所对应的起点），注释不能
写得很长，只要能表示是哪个控制语句控制范围的结束即可，这样便于阅读。
3、将注释与注释分隔符用一个空格分开，在没有颜色提示的情况下查看注释时，
这样做会使注释很明显且容易被找到。
4、不允许给块注释的周围加上外框。这样看起来可能很漂亮，但是难于维护。
5、每行注释（连同代码）不要超过120个字(1024×768)，最好不要超过80
字(800×600) 。
6、Java编辑器（IDE）注释快捷方式。Ctrl+/ 注释当前行,再按则取消注释。
7、对于多行代码的注释，尽量不采用“/*......*/”，而采用多行“//”注释，
这样虽然麻烦，但是在做屏蔽调试时不用查找配对的“/*......*/”。
8、注释作为代码切换开关，用于临时测试屏蔽某些代码。
试想一下，一个没有一句注释的程序源码，怎么读，一个程序要上万条代码不可能全部记得住哪一块是什么用，而且一个项目也不会是一个人独自完成，那样效率太低，多人合作就要给别人说明，每一块是什么用，方便他人使用，方便自己更正，而这些说明文字就是注释，注释不会被执行，不影响运行结果。
Java中代码的注释有三种：
// 注释一行
/* ...... */ 注释若干行
/** ...... */ 注释若干行，并写入 javadoc 文档
前两种比较容易理解，至于第三种，你学习Java看的api文档就是javadoc程序根据第三种的注释生成的。
扩展资料
注释就是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。注释是编写程序时，写程序的人给一个语句、程序段、函数等的解释或提示，能提高程序代码的可读性。
Java代码注释写的多，会影响到编译效率，但是不会影响到执行效率。
Java代码是先编译成字节码，然后被JVM解释执行的。
我做了个实验
TimeDemo 类
import java.util.ArrayList;
public class TimeDemo {
public static void main(String[] args) {
long start = System.currentTimeMillis();
ArrayListInteger list = new ArrayListInteger();
for (int i = 0; i 1000000; i++) {
list.add(i);
}
long end = System.currentTimeMillis();
System.out.println("本次执行耗费了"+(end-start)+"毫秒");
}
}
TimeDemo2
import java.util.ArrayList;
public class TimeDemo2 {
public static void main(String[] args) {
long start = System.currentTimeMillis();
ArrayListInteger list = new ArrayListInteger();
for (int i = 0; i 1000000; i++) {
list.add(i);
}
//用java.io生成了很多行的注释,
//注释
//注释
//注释
//注释
//注释
long end = System.currentTimeMillis();
System.out.println("本次执行耗费了"+(end-start)+"毫秒");
}
}
运行结果
当注释行数是1~1万行的时候. 能较快的编译
当注释行数达到1百万的时候,编译稍微慢一点
当注释行数达到1千万行的时候, CPU占用100%,卡了进1分钟也没有编译完成,只好强行关闭
结论:
简单明了的注释有助于程序猿对代码的读写
只有当注释行数极大的时候，才会严重的影响编译速度。 但不会影响执行速度
多注了些控制流程，希望我的注释能够对你有帮助：
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
public class GoodLucky extends JFrame implements ActionListener{
JTextField tf = new JTextField(); //实例化一个文本域
//设置两个按钮
JButton b1 = new JButton("开始");
JButton b2 = new JButton("停止");
boolean isGo = false;
//构造函数
public GoodLucky(){
b1.setActionCommand("start");//在开始按钮上设置一个动作监听 start
JPanel p = new JPanel(); //实例化一个可视化容器
//将两个按钮添加到可视化容器上面，用add方法
p.add(b1);
p.add(b2);
//在两个按钮上增加监听的属性,自动调用下面的监听处理方法actionPerformed(ActionEvent e)，如果要代码有更好的可读性，可用内部类实现动作
//监听处理。
b1.addActionListener(this);
b2.addActionListener(this);
//将停止按钮设置为不可编辑（即不可按的状态）
b2.setEnabled(false);
this.getContentPane().add(tf,"North"); //将上面的文本域放在面板的北方，也就是上面（上北下南左西右东）
this.getContentPane().add(p,"South"); //将可视化容器pannel放在南边，也就是下面
this.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); //设置用户在此窗体上发起 "close" 时默认执行的操作，参数EXIT_ON_CLOSE是使用 System exit 方法退出应用程序。仅在应用程序中使用
this.setSize(300,200); //设置面板大小，宽和高
this.setLocation(300,300); //设置面板刚开始的出现的位置
Cursor cu = new Cursor(Cursor.HAND_CURSOR); //用指定名称创建一个新的定制光标对象，参数表示手状光标类型
this.setCursor(cu); //为指定的光标设置光标图像，即设置光标图像为上面所创建的手状光标类型
this.setVisible(true); //将面板可视化设置为true，即可视，如果为false，即程序运行时面板会隐藏
tf.setText("welcome you! "); //设置面板的标题为欢迎
this.go(); //调用go方法
}
public void go(){
while(true){ //这里是死循环，也就是说用户不点击停止按钮的话他一直循环出现随机数，直到用户点击停止按钮循环才能推出，具体流程在actionPerformed方法中控制。
if(isGo == true){ //上面所定义的isGo的初始值为false，所以程序第一次到此会跳过
String s = ""; //设置空字符串
for(int j = 1; j = 7;j++){ //产生7个随机数
int i = (int)(Math.random() * 36) + 1;//每个随机数产生方式，这里定义灵活，可以自由定义随机数产生的方式
if(i 10){
s = s + " 0" + i; //如果产生的随机数小于10的话做处理：这里就牵扯到一个重要的概念，简单叙述一下：
/*
当一个字符串与一个整型数项相加的意思是连接，上面的s = s + " 0" + i的意思是字符串s链接0再连接整型i值，而不会导致0和整型的i相加，
产生的效果为s0i,由于s为空字符串（上面定义过的），所以当i小于零时，在个位数前面加上0，比如产生的随机数i为7的话，显示效果为 07.
*/
}else{
s = s + " " + i; //如果产生的随机数比10打的话，那么加上空格显示，即数字和数字之间有个空格
}
//以上循环循环七次，以保证能出现7个随机数
}
tf.setText(s); //将产生的随机数全部显示在文本域上，用文本域对象tf调用它的设置文本的方法setText(String)实现。
}
//以下为线程延迟
try{
Thread.sleep(10); //线程类同步方法sleep，睡眠方法，括号里的单位为ms。
}catch(java.lang.InterruptedException e){
e.printStackTrace(); //异常捕获，不用多说。
}
}
}
//以下是上面设置的事件监听的具体处理办法，即监听时间处理方法，自动调用
public void actionPerformed(ActionEvent e){ //传入一个动作事件的参数e
String s = e.getActionCommand(); //设置字符串s来存储获得动作监听，上面的start
/*
以下这个条件语句块的作用为：用户点击开始后（捕获start，用方法getActionCommand()），将命令触发设置为true，从而执行上面的go方法中的循环体（因为循环体中要求isGo参数为true,而初始为false）。
执行循环快产生随机数，并将开始按钮不可编辑化，而用户只可以使用停止按钮去停止。如果用户按下停止时，也就是没有传入参数“start”的时候，
执行else语句块中的语句，isGo设置为false，将不执行上面go中的循环语句块，从而停止产生随机数，并显示，并且把开始按钮设置为可用，而把
停止按钮设置为不可用，等待用户按下开始再去开始新一轮循环产生随机数。
*/
if(s.equals("start")){ //如果捕获到start，也就是用户触发了动作监听器，那么下面处理
isGo = true; //设置isGo为true
b1.setEnabled(false); //将开始按钮设置为不可用
b2.setEnabled(true); //将停止按钮设置为可用
}else{
isGo = false; //将isGo设置为false，isGo为循环标志位
b2.setEnabled(false); //设置停止按钮为不可用（注意看是b2,b2是停止按钮）
b1.setEnabled(true); //设置开始按钮为可用
}
}
public static void main(String[] args){
new GoodLucky(); //产生类的实例，执行方法
}
}
圣诞平安夜了，祝朋友开心快乐！
一般编程在1/4~1/3就可以了，其实编程的时候不单要关注注释的量，还要写的清晰、明了。注释的多少不是主要的，关键是能让别人看的时候能看明白。
另外在命名是也要特别注意，命名能都充分表现你的变量、方法、类的含义，这样也能起到注释的作用。
还有就是类、方法不能过大，方法十几行也就差不多了，太多可读性就比较差了。
注释的很详细了 还有什么不明白的可以给我留言
此外给楼主点建议，打好基础，这套代码乱七八糟，写的太烂了。不适合用来学习，要学习就找好代码，不然很容易被误导。
/**
*此类事dao层中的一个类 使用hibernate完成持久层的控制
*继承自抽象类AbstractDAO并实现了抽象类的相关方法
*主要包括获取图书列表，获取图书记录，添加图书信息，添加和更新图书信息，
*获取图书信息和判断判断是否可以删除图书信息这几个功能
*/
public class BookDAO extends AbstractDAO {
//无参数构造方法
public BookDAO() {
}
/**治理竟然加了个主方法，恕在下愚钝，除了添乱之外想不出别的解释
*也可能是测试阶段用来测试 然后忘记删除了
*/
public static void main(String[] args) {
// TODO Auto-generated method stub
}
/**
* 获取图书信息 根据关键字使用模糊查询 得到包含关键字的图书信息列表
*如果输入的book对象的bookName属性为控制或者空字符串 默认查询所有图书信息
*@pamar book 图书信息的持久化对象 应该对应数据库中的一张表bookinfo
*@pamar pager 应该是一个封装了分页逻辑的对象
*@return List 返回的数据库中包含book中关键字（图书名）的图书信息列表
*默认情况返回数据库中所有图书的信息，
*这里返回值设计成ListBookinfo会更好 当然由于集成的抽象类的限制改不了（抽象类设计的不好 ）
**/
public List getBookList(Bookinfo book,Pager pager) throws DataAccessException{
//hql语句 默认情况下 返回数据库中所有的图书信息
String hql = " from com.jframe.biz.book.Bookinfo book" +
" where 1=1 ";
/*如果book名存在且不是空串
*重新构造hql语句 添加限制条件 返回book名字的模糊查询结果集
*/
if(book.getBookName()!=null!"".equals(book.getBookName())){
hql += " and book.bookName like '%"+book.getBookName()+"%'";
}
//如果书的作者不为空且不是空串 添加限制条件 返回指定作者的模糊查询结果集
if(book.getAuthor()!=null!"".equals(book.getAuthor())){
hql += " and book.author like '%"+book.getAuthor()+"%'";
}
//创建查询对象 执行hql语句
Query query = this.getSession().createQuery(hql);
//以下两条记录设置了从数据库的第几条记录开始 查到第几条 用于分页
//设定结果集的大小 就是分页逻辑设定的每页显示的记录数
query.setMaxResults(pager.getPageSize());
//从分页中逻辑中传过来的起始记录开始查
query.setFirstResult((pager.getCurrentPage()-1)*pager.getPageSize());
//返回查询到的结果
return query.list();
}
/**
*查询指定条件的图书的记录数
*@pamar book 一个图书信息对象
*@return int 图书的记录数
*/
public int getBookCount(Bookinfo book) throws DataAccessException{
//设定默认的hql 查询所有的图书的记录
String hql = " select count(bookName) from com.jframe.biz.book.Bookinfo book" +
" where 1=1 ";
//如果图书名不为空且不是空串 添加限制条件--图书名的模糊查询
if(book.getBookName()!=null!"".equals(book.getBookName())){
hql += " and book.bookName like '%"+book.getBookName()+"%'";
}
// 如果图书作者不为空且不为空串 添加限制条件--图书作者的模糊查询
if(book.getAuthor()!=null!"".equals(book.getAuthor())){
hql += " and book.author like '%"+book.getAuthor()+"%'";
}
Query query = this.getSession().createQuery(hql);
//返回查询的结果集到list
List list = query.list();
//如果结果集对象不为空且存在结果
if(list!=nulllist.size()0)
//将结果集中第一个元素转换成整形然后返回
return ((Integer)query.list().iterator().next()).intValue();
else
//没有记录返回0
return 0;
}
/**
*添加图书信息
*@parma book 图书信息对象
*@return 很费解 为啥这个方法还有返回值，即使需要返回值也是布尔型的啊
*/
public Bookinfo addBookInfo(Bookinfo book) throws DataAccessException{
//创建hibernate模板对象
HibernateTemplate template = this.getHibernateTemplate();
//调用模板的保存方法保存图书信息
template.save(book);
//清理缓存或者说清理脏数据 检验内存中的持久态对象是否已经存入数据库
template.flush();
template.evict(book);
//以后返回值就不解释了 方法头上面有参数和返回值的解释
return getBookInfo(book);
}
/**
*保存或者更新方法 注意 这个方法在旧版的hibernate里有 貌似hibernate3.0以上版本就删掉了
*@parma book 图书信息对象
*@return 为啥这个和上个方法还有返回值，即使需要返回值也是布尔型的啊
*/
public Bookinfo saveBookInfo(Bookinfo book) throws DataAccessException{
//同上个方法 以后不解释
HibernateTemplate template = this.getHibernateTemplate();
//如果数据库中没有则插入 如果有则更新
template.saveOrUpdate(book);
return book;
}
/**
*删除指定图书
*@parma book图书信息
*@return void
*/
public void deleteBookInfo(Bookinfo book) throws DataAccessException{
HibernateTemplate template = this.getHibernateTemplate();
//调用模板的删除方法
template.delete(book);
}
/**
*根据书号查询图书信息
*@param book 图书对象
*@return 图书信息
*/
public Bookinfo getBookInfo(Bookinfo book) throws DataAccessException{
HibernateTemplate template = this.getHibernateTemplate();
//sql语句 查询指定书号的图书信息
String hql = " from com.jframe.biz.book.Bookinfo book" +
" where 1=1 and book.bookNo='"+book.getBookNo()+"'";
//调用查询的模板的查询类
List list = template.find(hql);
//将查询结果集的第一个值强制转换成对象返回
if(list!=nulllist.size()0)
return (Bookinfo) list.iterator().next();
else
return null;
}
/**
*r如果日志信息中记录的书号是可删除的 并且在数据库中存在则返回true
*/
public boolean isCanDelete(Bookinfo book) {
boolean flag = false;
HibernateTemplate template = this.getHibernateTemplate();
String hql = " from com.jframe.biz.log.Loginfo log" +
" where 1=1 and log.bookinfo.bookNo='"+book.getBookNo()+"'";
List list = template.find(hql);
if(list!=nulllist.size()0)
flag = false;
else
flag = true;
return flag;
}
}
我们在微信上24小时期待你的声音
解答本文疑问/技术咨询/运营咨询/技术建议/互联网交流
微信二维码
移动版官网