大家都是怎么做函数注释的

Question

一个是美观，一个是一目了然

Answer 1

/**
     * 获取分类商品列表
     * @param $shop_id 店铺id
     * @param $cate_id 分类id
     * @param $page    页码
     * @param $per_page 页数
     * @return mixed
     */

这是使用phpstorm自动生成的

Answer 2

首先注释是让人一目了然，但是跟美观没关系。。还有注释一般为两种，一种是代码行级别的，一种是方法级别的，方法级别一般要求用文档注释。

Answer 3

建议看下，PHP PSR代码标准编程规范
https://github.com/hfcorriez/...

Answer 4

这样的么

/**
 *
 *
 *                                        
 *                                  .. .vr       
 *                                qBMBBBMBMY     
 *                               8BBBBBOBMBMv    
 *                             iMBMM5vOY:BMBBv        
 *             .r,             OBM;   .: rBBBBBY     
 *             vUL             7BB   .;7. LBMMBBM.   
 *            .@Wwz.           :uvir .i:.iLMOMOBM..  
 *             vv::r;             iY. ...rv,@arqiao. 
 *              Li. i:             v:.::::7vOBBMBL.. 
 *              ,i7: vSUi,         :M7.:.,:u08OP. .  
 *                .N2k5u1ju7,..     BMGiiL7   ,i,i.  
 *                 :rLjFYjvjLY7r::.  ;v  vr... rE8q;.:,, 
 *                751jSLXPFu5uU@guohezou.,1vjY2E8@Yizero.    
 *                BB:FMu rkM8Eq0PFjF15FZ0Xu15F25uuLuu25Gi.   
 *              ivSvvXL    :v58ZOGZXF2UUkFSFkU1u125uUJUUZ,   
 *            :@kevensun.      ,iY20GOXSUXkSuS2F5XXkUX5SEv.  
 *        .:i0BMBMBBOOBMUi;,        ,;8PkFP5NkPXkFqPEqqkZu.  
 *      .rqMqBBMOMMBMBBBM .           @kexianli.S11kFSU5q5   
 *    .7BBOi1L1MM8BBBOMBB..,          8kqS52XkkU1Uqkk1kUEJ   
 *    .;MBZ;iiMBMBMMOBBBu ,           1OkS1F1X5kPP112F51kU   
 *      .rPY  OMBMBBBMBB2 ,.          rME5SSSFk1XPqFNkSUPZ,.
 *             ;;JuBML::r:.:.,,        SZPX0SXSP5kXGNP15UBr.
 *                 L,    :@huhao.      :MNZqNXqSqXk2E0PSXPE .
 *             viLBX.,,v8Bj. i:r7:,     2Zkqq0XXSNN0NOXXSXOU 
 *           :r2. rMBGBMGi .7Y, 1i::i   vO0PMNNSXXEqP@Secbone.
 *           .i1r. .jkY,    vE. iY....  20Fq0q5X5F1S2F22uuv1M; 
 *
 *
 *
 * @auther Null.yang<[e-mail]>
 *
 * "不要误会，我不是针对你，我是说在做的各位，都是垃圾。"
 */

Answer 5

注释标准：http://flc.ren/2015/10/248.html

/**
 *
 * ━━━━━━神兽出没━━━━━━
 * 　　　┏┓　　　┏┓
 * 　　┏┛┻━━━┛┻┓
 * 　　┃　　　　　　　┃
 * 　　┃　　　━　　　┃
 * 　　┃　┳┛　┗┳　┃
 * 　　┃　　　　　　　┃
 * 　　┃　　　┻　　　┃
 * 　　┃　　　　　　　┃
 * 　　┗━┓　　　┏━┛Code is far away from bug with the animal protecting
 * 　　　　┃　　　┃    神兽保佑,代码无bug
 * 　　　　┃　　　┃
 * 　　　　┃　　　┗━━━┓
 * 　　　　┃　　　　　　　┣┓
 * 　　　　┃　　　　　　　┏┛
 * 　　　　┗┓┓┏━┳┓┏┛
 * 　　　　　┃┫┫　┃┫┫
 * 　　　　　┗┻┛　┗┻┛
 *
 * ━━━━━━感觉萌萌哒━━━━━━
 */

Answer 6

其实一段好的代码是不需要注释的，优雅的代码能够直接展示它的功能，只有晦涩难懂的地方才需要注释加以说明。变量名、方法名尽量一目了然，别人一看就知道这个变量是做什么的，这个方法是做什么的，这时根本是不需要对这个变量、方法增加额外的注释