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) {}

}