java优雅注释原则和代码格式列举

一、java的三种注释类型

• 单行注释：// ......
• 块注释：/* ...... */
• 文档注释：/** ...... */

二、指导原则

• 注释不能美化糟糕的代码，碰到糟糕的代码就重新写吧。
• 用代码来阐述你的意图，好的代码就是最好的注释。
• 错误的注释比不注释更可怕。
• 大括号后不要加注释，建议另起一行。
• 注释调的代码建议删掉。
• 废话式注释，循规式注释，误导性注释都应该删掉。
• 巧用标记（TODO、FIXME）
• 注释要放在距离其描述代码最近的位置。

三、代码格式列举

这里和大家聊下代码基本格式，好的代码格式会让维护者更容易阅读和理解。

package effective.code.up;

/**
 * 
 * <p>Description: 这里写出这个类的描述，新写的类一定要带上日期和作者</p>  
 * @author wudiffs
 * @date 2019年5月7日
 */
public class EffectiveCodeFormat {

	public static void main(String[] args) {
		
		// 缩进4个空格
		String say = "hello";
		// 运算符左右必须有一个空格
		int flag = 0;
		// 关键词if与括号之间必须有一个空格，括号内的f与左括号，0与右括号不需要空格
		if (flag == 0) {
			System.out.println(say);
		}
		
		// 左大括号前加空格且不换行，左大括号后换行
		if (flag == 1) {
			System.out.println("world");
		// 右大括号前换行，右大括号有else，不用换行	
		} else {
			System.out.println("ok");
		// 在右大括号直接结束，则必须换行	
		}
		
		/*当行字符数限制不超过120个字符，超出需换行，换行遵循如下原则：
		 * 1.第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进
		 * 2.运算符与上下文一起换行
		 * 3.方法调用的点符号与下文一起换行
		 * 4.方法调用多个参数，需要换行时，在逗号后进行
		 * 5.括号前不要换行
		 */
        StringBuffer sb = new StringBuffer();
        sb.append("AA").append("AA").append("AA").append("AA").append("AA").append("AA").append("AA").append("AA")
            .append("BB").append("BB").append("BB").append("BB").append("BB").append("BB").append("BB").append("BB")
            .append("BB").append("BB").append("BB").append("BB");		
		
		// 不同逻辑，不同语义，不同业务的代码之间插入一个空行分隔开来以提升可读性。
		System.out.println("six six six up up up");
	}
	
	/**
	 * 方法参数在定义和传入时，多个参数逗号后边必须加空格。方法描述要加上。
	 * @param sa
	 * @param sb
	 * @param sc
	 */
	public static void doSomething(String sa, String sb, String sc) {}

}