V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
legiorange
V2EX  ›  Java

为何阿里规约在 Java 中不能行尾注释?你们有什么看法?

  •  1
     
  •   legiorange · 2019-07-26 09:46:06 +08:00 · 17264 次点击
    这是一个创建于 1949 天前的主题,其中的信息可能已经有所发展或是发生改变。
    59 条回复    2019-08-05 14:40:31 +08:00
    wenzhoou
        1
    wenzhoou  
       2019-07-26 09:48:33 +08:00 via Android   ❤️ 1
    人家的家规,开心就好。
    shuizhengqi
        2
    shuizhengqi  
       2019-07-26 09:51:31 +08:00   ❤️ 4
    不规定的话,如果大家都在行首注释,你来一个行尾注释,那你这个注释到底是针对上面的还是下面的?除了你,谁能懂
    skiy
        3
    skiy  
       2019-07-26 09:55:33 +08:00   ❤️ 1
    难道我看代码得从下面开始看的吗?每个 IDE 编辑器打开时都是头部显示的。注释一目了然,你却还要别人拉到最底部看注释才懂此文件干嘛用的。拉到下面了,我肯定都瞄了一遍代码了。
    fan123199
        4
    fan123199  
       2019-07-26 09:56:42 +08:00   ❤️ 1
    @shuizhengqi 没有行首注释啊。我猜是因为许多人其实是要对一段代码注释,但只注释到了首行行末,这样可能不利于理解。另外 ide 对行末的注释也不会生产文档。 但是,我要说的是,很多时候行末注释是有效提高理解效率,我觉得可以用。
    maichael
        5
    maichael  
       2019-07-26 09:57:19 +08:00   ❤️ 9
    没什么看法,代码规范这种东西大多数情况下都不是为了分对错,而是为了减少争议。
    fan123199
        6
    fan123199  
       2019-07-26 09:58:02 +08:00
    @skiy 是行末,不是文件末。
    hand515
        7
    hand515  
       2019-07-26 09:58:53 +08:00   ❤️ 1
    格式化有对一行多少个字符规定
    chendy
        8
    chendy  
       2019-07-26 09:59:33 +08:00   ❤️ 1
    个人观点:因为非文档注释通常都是要说明一些特殊情况,所以最好出现在代码前,先知道要做什么再看到代码
    另外行尾注释比较容易超出宽度限制
    legiorange
        9
    legiorange  
    OP
       2019-07-26 10:20:17 +08:00
    @shuizhengqi 行首注释 意思是这样吗。。?
    // base
    var base = Base ;
    W1angMh
        10
    W1angMh  
       2019-07-26 10:21:42 +08:00
    @skiy 兄弟看清是行末注释
    W1angMh
        11
    W1angMh  
       2019-07-26 10:24:19 +08:00   ❤️ 1
    @legiorange 是的,某行代码或者某个代码块的注释写在该行的上方(代码块写在第一行的上方)
    qwerthhusn
        12
    qwerthhusn  
       2019-07-26 10:24:49 +08:00   ❤️ 6
    别人的家规,参考一下得了,至少我感觉 这个没必要。

    还有阿里的 IDEA 代码检查插件,我感觉啥有用的东西都检查不出来,检查出来的都是一些不关痛痒的东西。。

    不过 IDEA 自带的 Inspect Code 是真的流批,只要代码那块黄了,八成是有问题的或者可以优化的
    skiy
        13
    skiy  
       2019-07-26 10:30:24 +08:00
    行尾是指:
    legiorange
        14
    legiorange  
    OP
       2019-07-26 10:32:23 +08:00
    @skiy String id = params.get("c_Id"); //班级 ID
    类似这样。行尾行末是一个意思。
    skiy
        15
    skiy  
       2019-07-26 10:32:59 +08:00   ❤️ 2
    var abc = 1; // 这种行末注释对吧?

    如果这种要求,我觉得没必要了。

    有时要定义一堆初始值时,我就是

    var abc = 1; // abc 的注释
    var bcd = 2; // bcd 的注释



    // abc 的注释
    var abc = 1;

    // bcd 的注释
    var bcd = 2;

    感觉这样挺影响阅读的
    darlinghsu
        16
    darlinghsu  
       2019-07-26 10:34:05 +08:00   ❤️ 1
    @skiy #13
    大概是

    demo() { //这是 xxxxx

    }

    我的习惯是:

    //这是 xxxx
    demo() {

    }
    yanguangs
        17
    yanguangs  
       2019-07-26 10:35:39 +08:00
    阿里家规罢了.
    oxoxoxox
        18
    oxoxoxox  
       2019-07-26 10:35:51 +08:00
    这和“缩进应该用四个 space、还是两个 space、还是一个 tab ”这种问题有什么区别?
    laoyur
        19
    laoyur  
       2019-07-26 10:36:44 +08:00
    @skiy > 行尾是指:

    ??承认一句看错了很难吗
    skiy
        20
    skiy  
       2019-07-26 10:38:16 +08:00   ❤️ 3
    @darlinghsu 如果是代码块,我习惯放在前面

    // abc 的注释
    abc () {

    }

    但是 if else 功能好难用。。。

    // abc
    if abc {

    // else 这里放置注释,IDEA 不太方便
    } else { // 有很多人是放在这里注释,感觉这种情况放在这里注释很方便

    }
    daozhihun
        21
    daozhihun  
       2019-07-26 10:38:40 +08:00 via Android
    人家自己定的规定,觉得好就采用,觉得不好就理会就是咯
    skiy
        22
    skiy  
       2019-07-26 10:39:23 +08:00
    @laoyur 我没有承认错了吗?我是要换行写代码时,按了回车键。没见我用了分号吗?
    uyz
        23
    uyz  
       2019-07-26 10:39:55 +08:00   ❤️ 1
    for(j=0; j<array_len; j+ =8)
    {
    total += array[j+0 ];
    total += array[j+1 ];
    total += array[j+2 ]; /* Main body of
    total += array[j+3]; * loop is unrolled
    total += array[j+4]; * for greater speed.
    total += array[j+5]; */
    total += array[j+6 ];
    total += array[j+7 ];
    }
    laoyur
        24
    laoyur  
       2019-07-26 10:44:01 +08:00
    @skiy > 我没有承认错了吗?我是要换行写代码时,按了回车键。没见我用了分号吗?

    我错了,抱歉,误伤了。写回复的时候只看到「行尾是指:」你这一条回复,还以为你故意装糊涂反问什么是行尾呢
    xnode
        25
    xnode  
       2019-07-26 10:44:10 +08:00
    是为了减少这样的帖子,如果允许在行尾注释,那么就会有人发帖问为什么不能在行首注释
    zsdroid
        26
    zsdroid  
       2019-07-26 10:51:09 +08:00   ❤️ 1
    我用的行首,这样代码看上去不会密密麻麻的堆在一起
    polebug
        27
    polebug  
       2019-07-26 10:51:22 +08:00
    我觉得没毛病 我观察过一般人
    定义变量的时候 习惯行末注释
    定义函数的时候 习惯在上方一行注释

    我猜是因为 定义变量 比较短且密集

    规定不能行末注释也挺好的 比如很长很长的类定义后面可不会再有注释了(比如 java 可真是又臭又长
    brust
        28
    brust  
       2019-07-26 10:53:42 +08:00   ❤️ 1
    我也是混搭
    但是我习惯是
    var abc = 1; // abc 的注释
    var bcd = 2; // bcd 的注释
    如果
    // abc 的注释
    var abc = 1;

    // bcd 的注释
    var bcd = 2;
    如果这种局部变量太多
    这样可能一个方法一个屏幕看不完
    W1angMh
        29
    W1angMh  
       2019-07-26 11:14:03 +08:00   ❤️ 1
    阿里 Java 开发手册里有三个建议级别:强制 > 推荐 > 参考,“方法内部的单行注释,在被注释语句的上方另起一行”属于强制级别
    Mogugugugu
        30
    Mogugugugu  
       2019-07-26 11:22:20 +08:00
    因为我没有带鱼屏,另外注释比较长换行咋解决?
    VoidChen
        31
    VoidChen  
       2019-07-26 11:39:41 +08:00
    @skiy 这样呢?
    // abc
    if abc {

    /
    } else {
    // 放在这里注释

    }
    chocotan
        32
    chocotan  
       2019-07-26 11:45:06 +08:00
    人家的家规,开心就好 +1
    opengps
        33
    opengps  
       2019-07-26 12:20:30 +08:00 via Android
    可能是屏幕都是竖着用,竖着看方便吧
    opengps
        34
    opengps  
       2019-07-26 12:23:56 +08:00 via Android   ❤️ 1
    回答个正规的,可能是代码审查工具更利用统计
    行位注释可能会跟转移字符的斜杠冲突识别不准
    passerbytiny
        35
    passerbytiny  
       2019-07-26 13:12:48 +08:00
    家规不是行规。
    如果你不是打算进去,那么还是建议参照谷歌的规范: https://google.github.io/styleguide/javaguide.html
    jinliming2
        36
    jinliming2  
       2019-07-26 13:26:29 +08:00 via iPhone   ❤️ 1
    我觉得楼上都进入了一个误区:不能在行尾注释就一定要在上一行注释,这没问题。但是允许在行尾注释,就不能在上一行注释了吗?肯定也可以啊!
    所以,该行尾注释就行尾注释,该上一行注释就上一行注释,该用块注释就用块注释。

    规则是为了代码更好看易读,统一可以方便理解。但是如果规则的出现导致代码变得不可读,那就得不偿失了!
    所以,所有的代码格式化工具都会提供忽略的功能,毕竟工具都是死的,没有办法根据实际代码情况做出调整(别跟我说接入 AI,毕竟现在 AI 也不是十分可靠)。

    所以,可以有规定,但是也要根据实际情况变通!
    人是活的!
    AlphaTr
        37
    AlphaTr  
       2019-07-26 13:32:55 +08:00 via iPhone
    行如果比较长,行尾注释就不适合了;但这个不太好规则化程序验证检测,所以直接禁用掉
    gabezhao
        38
    gabezhao  
       2019-07-26 13:44:36 +08:00
    @AlphaTr 我觉得也是这样的,看个注释还得向后拉
    skiy
        39
    skiy  
       2019-07-26 13:50:24 +08:00
    @VoidChen

    f abc {

    /
    } else {
    // 放在这里注释的话,就感觉像是下一行的注释,不像这段代码块的注释了。


    }
    LukeChien
        40
    LukeChien  
       2019-07-26 14:20:09 +08:00 via Android
    听说是,代码审计工具会判断注释所属语句,定义变量没有注释会警告
    mikulch
        41
    mikulch  
       2019-07-26 15:01:05 +08:00
    国际上都是首行注释。
    Aresxue
        42
    Aresxue  
       2019-07-26 15:06:20 +08:00
    看着行数多。。。逃
    javaWeber
        43
    javaWeber  
       2019-07-26 15:07:02 +08:00
    alt+Enter。再点击那个 no inspect,就可以取消这个检查了。
    viator42
        44
    viator42  
       2019-07-26 15:10:02 +08:00
    行尾没什么不好的,定义变量的时候很清楚
    现在显示屏的分辨率都很高,超宽应该早就不是什么问题了
    nekoneko
        45
    nekoneko  
       2019-07-26 15:23:13 +08:00
    习惯这样
    /* 注释 **/
    private static fianl Xxxx XXXXXX = XXXXX;

    // 注释
    int a = 0;


    // 注释
    if(){


    }
    //注释
    else{

    }
    metrxqin
        46
    metrxqin  
       2019-07-26 15:29:46 +08:00
    我挺爱在行尾注释,但是我的同事 IDE 有阿里规约插件,每次提交内容好多变动都是纠正这个问题。
    MotherShip
        47
    MotherShip  
       2019-07-26 16:31:12 +08:00
    就应该禁掉行尾注释

    对不齐的行尾注释看着难受,对齐的。。改完代码还得对齐一次

    何况我没有带鱼屏
    real3cho
        48
    real3cho  
       2019-07-26 16:37:00 +08:00
    你怎么不戴帽子呢
    rizon
        49
    rizon  
       2019-07-26 17:09:14 +08:00
    禁止行尾注释有个不好的地方就是比如一个 if 语句,你想对 if 的条件做注释,那么这个注释是针对 if 条件的呢还是针对整个 if 块的呢,这时候就很难受,唉~

    不过行尾注释的危害其实更大,比如不够显眼,要往左侧拉滚动条
    cco
        50
    cco  
       2019-07-26 17:17:42 +08:00
    怎么都可以,好看就行,能一屏装得下就行。
    dr2009
        51
    dr2009  
       2019-07-26 17:52:34 +08:00
    一些变量的定义放行尾看着也挺舒服的
    kuroismith
        52
    kuroismith  
       2019-07-26 17:57:17 +08:00
    行首注释还是行尾注释其实并不重要
    但是如果没有这个规定, code review 的时候就会像这楼里一样为了这种屁事吵来吵去
    kuroismith
        53
    kuroismith  
       2019-07-26 17:59:07 +08:00
    @opengps 编译器分得清代码审核工具会分不清吗? 除非是审查工具蠢到直接用简单的正则来匹配.
    murmur
        54
    murmur  
       2019-07-26 18:00:21 +08:00
    把这行注释掉就可以 反正现在都是大屏幕 我们一行的代码已经设置到 250-300 个字符了
    tslling
        55
    tslling  
       2019-07-26 18:33:02 +08:00 via Android
    规矩没什么好说的。要说原因的话可能是行尾注释比换行注释更容易被忽略。再就是对 diff 友好一点,比如修改了注释的时候不换行还要仔细对比,换行注释的话 diff 结果更明了。注释和代码本来是两个不同的东西,我觉得换行注释更合理一点,如果公司规定了一定要换行那肯定要遵守,但是应该没有规定一定不能换行的公司吧。。。
    jason19659
        56
    jason19659  
       2019-07-26 21:57:27 +08:00
    [强制] 方法内部单行注释,在被注释语句上方另起一行,使用 //注释。方法内部多行注释 使用 /* */注释,注意与代码对齐。
    [强制] 类、类属性、类方法的注释必须使用 Javadoc 规范,使用 /**内容*/格式,不得使用 // xxx 方式。
    weakish
        57
    weakish  
       2019-07-26 22:46:22 +08:00
    以下纯属虚构,如有雷同,纯属巧合。

    1. 行尾注释一般是针对某一行代码的。这种针对某一行代码的注释很多情况下是没有必要的,剩下的一些情况,不如把代码换一种更明白清晰的写法。真正需要注释某一行代码的情景是很少的。比如 Python 的 PEP 8 也推荐「 Use inline comments sparingly.」
    2. 因为 1,很多项目的代码中极少出现行尾注释。
    3. 某个人或者某群人编写代码风格规范的时候因为 2 的缘故,所以加上了不准行尾注释这条,但是出发点可能只是因为很少看到行尾注释,所以看到行尾注释感觉不顺眼,并不清楚 1 的原因。因此搞了一刀切,一律不准(很可能也有一刀切方便贯彻的因素)。
    cyspy
        58
    cyspy  
       2019-07-27 15:06:13 +08:00
    写 RDD、Stream 和 builder 的时候用行尾注释很自然
    jaylee4869
        59
    jaylee4869  
       2019-08-05 14:40:31 +08:00
    考虑代码+注释在屏幕上的长度。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   5943 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 36ms · UTC 03:26 · PVG 11:26 · LAX 19:26 · JFK 22:26
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.