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

}

转载于:https://www.cnblogs.com/wudiffs/p/11051287.html