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

准备修改离职同事的一个项目,所有代码只有开头一行注释,看着头晕。

  •  
  •   go522000 · 98 天前 · 5631 次点击
    这是一个创建于 98 天前的主题,其中的信息可能已经有所发展或是发生改变。

    截一张图给大家感受一下。 https://static01.imgkr.com/temp/372735ce126444a283e8856dd5a4c56e.png

    没办法修改,实在想不通这个同事是什么意思。 是对自己代码的自信? 还是故意留坑?

    唉,我自己 15 号也要走了,只能和大老板说自己能力有限,无能为力。

    第 1 条附言  ·  98 天前
    感谢大家指点,看来确实是我能力有限。

    可能是我过几天也要离职了,所以看一眼项目注释太少就直接没兴趣看代码了。
    第 2 条附言  ·  97 天前
    感谢各位指点,昨天认真把项目给重新浏览一下。
    同事的代码写得确实很好,主要是我自己没耐心的原因,一心只想跑路,误会同事了。
    XiLingHost
        1
    XiLingHost  
       98 天前   ❤️ 4
    这个命名看着挺舒服的,似乎也不是很需要注释吧
    monkeylmj
        2
    monkeylmj  
       98 天前   ❤️ 1
    个人觉得注释并不是越多越好,最舒服的代码是通过合理命名就能看懂意思,根本不需要注释
    mayday526
        3
    mayday526  
       98 天前   ❤️ 5
    这不是看着还行吗,还需要啥注释?
    rabbbit
        4
    rabbbit  
       98 天前   ❤️ 5
    你们公司允许就这么把代码贴出来?
    CookCoder
        5
    CookCoder  
       98 天前   ❤️ 2
    这代码很差?
    BiChengfei
        6
    BiChengfei  
       98 天前
    除了方法上注释不要使用单行注释,其他没什么问题。这个业务逻辑感觉挺简单,写的也很清晰
    cpstar
        7
    cpstar  
       98 天前
    这就当一个黑盒,不也没啥问题啊
    codespots
        8
    codespots  
       98 天前   ❤️ 10
    连个业务逻辑相关的说明都没有,那么多人觉得这叫还行?可能我水平不够,所以只能在写代码时多加注释了
    ration
        9
    ration  
       98 天前 via Android   ❤️ 2
    这业务代码确实需要多注释文档才容易理解。不然要花很多时间。可能改成面向对象的写法好点。
    haah
        10
    haah  
       98 天前
    你有时间发帖,却没时间怼他?
    461da73c
        11
    461da73c  
       98 天前
    这 PHP 写的挺干净的。
    go522000
        12
    go522000  
    OP
       98 天前   ❤️ 1
    向支持不用注释的各位请教一下,第 619 行,JoinService::JoinField(...) 这个函数里面大约还有 40 多行代码(整个文件都没注释),大家在不把代码过一遍的情况下,能不能猜出这一行是什么意思呢?最后会返回什么内容呢?
    go522000
        13
    go522000  
    OP
       98 天前
    @haah 哈,不怼他,我还有 9 天也离职了,直接告诉老板我能力有限最方便了。
    anerevol
        14
    anerevol  
       98 天前
    @go522000 就是 useraddress 存的是 province_id city_id , 要 join 表查一下对应的 province_name city_name 这些吧
    其实这种通用的业务规则还好 那种专有的业务规则不写注释才是会死人的
    fgwmlhdkkkw
        15
    fgwmlhdkkkw  
       98 天前
    我觉得写的挺好的……
    rabbbit
        16
    rabbbit  
       98 天前
    @go522000
    都要走了还改啥啊.把图删了吧,别让你们老板抓住把柄.
    zhzy0077
        17
    zhzy0077  
       98 天前   ❤️ 4
    说实话这代码比绝大多数屎山强太多 最要命的其实不是这个 JoinService 顶天了点进去看一遍 反而是 $flag, getCode, $data 这些名字 比如$flag == 0 的判断虽然可以从 if 里看出应该是判断发货还是收货的 这样的变量名其实毫无意义 还不如 abcd 至少写的人会有愧疚感
    cloudsigma
        18
    cloudsigma  
       98 天前
    删图吧
    Building
        19
    Building  
       98 天前
    我觉得写的挺好的……
    zengguibo
        20
    zengguibo  
       98 天前
    这种代码一看就好理解,那种大神写的奇巧淫技才看不懂呢
    Orenoid
        21
    Orenoid  
       98 天前
    说烂不至于,说它很清晰可就算了吧。
    这么一大堆业务逻辑,不做分段注释,也不做进一步的函数封装。代码里也有明显的分段,每一段稍微注释一下不难吧?
    CookCoder
        22
    CookCoder  
       98 天前
    @go522000 根据变量名字,地址信息,然后后面的省市 ID ,差不多根据 id 找到更具体的省市信息,这一段也需要注释么?
    CookCoder
        23
    CookCoder  
       98 天前
    不过,注释写的肯定很差,输入输出起码写,每一个关键变量和业务逻辑起码加一个,619 行这样的不需要注释。
    meeop
        24
    meeop  
       98 天前
    代码挺整洁的,个人觉得并不需要太多注释

    以及程序员最讨厌别人不写注释,同时最讨厌自己写注释

    注释和文档由于会因为代码变更缺乏维护而辞不达意,更好的做法还是把代码结构写清晰,变量名说清楚
    CookCoder
        25
    CookCoder  
       98 天前
    说还行的原因是,起码根据变量名字,方法名字,几乎已经看明白这些代码准备干什么,难道说个还行都过分么?
    really28
        26
    really28  
       98 天前   ❤️ 1
    又不是不能用,建议各位熟读 https://coderlmn.github.io/frontEndCourse/unmaintainable.html

    提升自己核心竞争力。

    🐶
    GeorgeGalway
        27
    GeorgeGalway  
       98 天前
    作为多年的 Phper ,这代码写的,确实还不错
    caixiangyu17
        28
    caixiangyu17  
       98 天前   ❤️ 1
    这命名不太行呀,各种 foo ,v ,r ,k ,data ,temp
    不过主要问题是方法太长了,我们 kotlin 项目 linting 要求 function 少于 40 行,一行少于 120char ,多了过不了 pipeline
    QlanQ
        29
    QlanQ  
       98 天前
    作为多年的 Phper ,这代码写的,确实还不错
    forbreak
        30
    forbreak  
       98 天前
    并不是注释越多越好啊。。。。
    mingl0280
        31
    mingl0280  
       98 天前
    这代码还要注释?
    @go522000 619 应该是返回一个集合,包含省市区的地址(字符串)。这个有啥看不懂的?
    ytmsdy
        32
    ytmsdy  
       98 天前   ❤️ 1
    小伙子,你太年轻了。
    至少变量命名清晰,结构也不乱。
    你是没有见过糟糕的代码!
    alanyuan
        33
    alanyuan  
       98 天前 via iPhone
    就这么把公司代码发出来,建议删帖&拉黑
    bugFactory
        34
    bugFactory  
       98 天前
    @really28 大佬,看了下,真是牛逼坏了呀
    mrgeneral
        35
    mrgeneral  
       98 天前
    看着还行。

    你把屏幕整宽点,去掉软换行,就会发现还挺整洁的,基本都是参数转化和提取而已。
    pengtdyd
        36
    pengtdyd  
       98 天前
    这就看懵了???小伙子,你太年轻了。1000 行没有注释的 SQL 就问你怕不怕!!!话说 SQL 没注释也正常。
    fyooo
        37
    fyooo  
       98 天前
    后续还是不要贴代码吧,严重违背职业道德
    ZoR
        38
    ZoR  
       98 天前
    代码看完后 感觉还行能猜到百分之 8 90%了,还是太年轻 有的代码看完以后 不知所云 让人欲仙欲死
    lap510200
        39
    lap510200  
       98 天前
    这已经算好的了 。。
    lap510200
        40
    lap510200  
       98 天前
    @ZoR 觉得还行的才是久经沙场,比起代码缺注释,数据库字段缺注释的老项目都有很多
    cryboy007
        41
    cryboy007  
       98 天前
    觉得挺好的,命名和很规范
    liudaolunhuibl
        42
    liudaolunhuibl  
       98 天前   ❤️ 1
    你应该需要这个需求的需求文档、设计文档等等,这些文档里的内容加上这个代码足够,总不能我把需求背景和设计思路都写在代码里吧
    Jooooooooo
        43
    Jooooooooo  
       98 天前
    代码没有业务逻辑的注释写的再漂亮也不行.
    jackbrother
        44
    jackbrother  
       98 天前
    有注释不代表是好代码,好的代码让你一眼就能看出来它是做什么的。说实话,反而是代码越不清晰的情况下,才需要去刻意注释,因为写下这段代码的人都可能不知道它在做什么。
    zengzizhao
        45
    zengzizhao  
       98 天前
    业务逻辑说明要写在代码的注释里?
    难道不应该去看需求文档、设计文档之类的文档吗
    如果业务逻辑很复杂,岂不是要把文档粘贴一份到代码里才叫好?
    yiqiao
        46
    yiqiao  
       98 天前
    能看懂,不过还是可以改进的
    第一个 flag 判断是写的一样的代码吗?
    看起来是顺序和参数不一样,再封装一下不就可以共用了吗?
    我也同意注释不用写到代码里,这通常是未实现功能或者是放到 TODO 里面,做完就删了。
    Zhengqing
        47
    Zhengqing  
       98 天前 via iPhone
    给院长和导师同时发一封邮件就好了 院长和导师的邮箱都很好找的
    yanqing07
        48
    yanqing07  
       98 天前
    坐等 LZ 去新公司后的吐槽~
    我就放下话了,新公司代码肯定比这个差~哈哈哈哈
    sun019
        49
    sun019  
       98 天前
    这代码写的规矩 算不错的了
    v2lf
        50
    v2lf  
       97 天前
    @BiChengfei 这好像是 php , 每种语言风格不同吧,go 源码单行都比较多
    v2lf
        51
    v2lf  
       97 天前
    说实话,这个还行。 要是功能再细化和内聚,就更美啦。
    而且,注释多也不一定好,有些真是废话连篇
    mengzhuo
        52
    mengzhuo  
       97 天前
    写得挺舒服的啊,这都算屎山的怕是没见过真屎山。
    某鹅某业务那 800 行带视图的 SQL+乱封装的代码是真开眼了
    vainl1
        53
    vainl1  
       97 天前   ❤️ 1
    Biexl
        54
    Biexl  
       97 天前
    你可能没见过更头痛的代码。当然了如果可以把这一大段代码拆分成多个 function ;将 0 ,1 使用常量或枚举定义;以及个别无含义的变量名改改。在没有 review 的情况下,这种业务代码基本不太会动了。
    panlatent
        55
    panlatent  
       97 天前
    总体上还算比较清晰,能看出来做什么 。但如果能改进一下或者加点注释能够节省其他人的时间,命名有点偷懒,函数行数多多,应该拆分成多个函数。里面的空行好评。

    好的代码应该是不需要或很少需要注释的,注释只是手段,最终还是为可读性服务。 而且有的时候写业务恰饭的时候,每那么多时间和精力去顾虑太多,及格或者良就差不多了。

    ---

    说点别的

    对于 PHP 来说,注释( PHPDoc )很多时候还为 IDE 、文档生成器以及测试框架服务,这方面最好多注意下。PHP 是动态类型,早期语言特性不丰富(类型标注),IDE 支持有限,只能通过加 PHPDoc 来优化编码体验。现代 PHP 已经在绝大多数地方支持类型标注,以及支持注解。PHPStorm 以及部分测试框架甚至提供有限的泛型支持。

    利用好代码检查,没有警告,包括没有拼写错误。当在 IDE 中想要用到某段代码却不能获得智能补全(或提示)时,就要考虑代码(注释)是不是可以再优化优化或者换 IDE 了。
    DCELL
        56
    DCELL  
       97 天前
    我的同事要是代码都写这样,我都能笑醒
    ETO
        57
    ETO  
       97 天前
    这代码写得还可以呀
    cxshun
        58
    cxshun  
       97 天前
    感觉代码命名啥的挺舒服的,而且逻辑也不复杂,这水平很不错了,不需要啥额外的注释啊
    zw1one
        59
    zw1one  
       97 天前
    写得很好 代码即注释 觉得看起来不直观你可以补注释
    reneiw
        60
    reneiw  
       97 天前
    就这断行,超级恶心
    yxzblue
        61
    yxzblue  
       97 天前
    没注释 不知道加上注释啊,又不是什么复杂的算法和逻辑……加一些注释的事情,何必要辞职
    JamesR
        62
    JamesR  
       97 天前
    我个人有个几年前的项目,已运行好几年了,早忘了怎么写得,为什么这么写,那些代码注释全面,包括所有的 if 都给注释上了,前段时间客户让我改个小地方,看注释迅速熟悉项目,找到问题,半天搞定。
    如果没有注释,碰到每次隔一年多,要修改某处的情况,每次修改都要重复浪费时间再熟悉项目。有时时间成本会高到无法再去修改。

    注释越多,理解越省力,否则改起来需要先花很多时间熟悉业务。
    注释是否划算,要看这个人是不是几年后还会修改这个项目了。
    JamesR
        63
    JamesR  
       97 天前
    上面说的是纯个人项目,注释非常详细,公司的项目我注释就少多了,每个函数简要注释下用途,少数难点也注释下即可。
    funtrip
        64
    funtrip  
       97 天前
    (你同事上不上 v2
    Eric2022
        65
    Eric2022  
       96 天前
    @really28 真有意思
    Quidquid latine dictum sit, altum sonatur.
    (随便用拉丁文写点啥都会显得高大上。)
    Eric2022
        66
    Eric2022  
       96 天前
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2443 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 98ms · UTC 12:08 · PVG 20:08 · LAX 05:08 · JFK 08:08
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.