V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
• 请不要在回答技术问题时复制粘贴 AI 生成的内容
drymonfidelia
V2EX  ›  程序员

只有一人维护的项目一般需要写注释和 commit message 吗?好像没什么必要的样子,写了从来没看过

  •  
  •   drymonfidelia · 3 天前 · 3714 次点击
    45 条回复    2024-12-09 23:30:06 +08:00
    Remember
        1
    Remember  
       3 天前   ❤️ 1
    不写注释不用说十年后了,就是一年后,你再看都很费劲。
    passive
        2
    passive  
       3 天前 via Android   ❤️ 1
    有些地方不写注释,下个月你就不认识了
    不管理好 commit ,写 changelog 或者 bisect 的时候很困扰
    kk2syc
        3
    kk2syc  
       3 天前
    三个月前自己反编译 app 写了一个开小区门禁的 http-api ,前几天 app 更新要重新适配参数了,代码打开发现一点印象都没有,以至于从头看一遍自己的屎山。
    iintothewind
        4
    iintothewind  
       3 天前   ❤️ 2
    好的代码,不需要太多注释,
    但好的代码肯定有合理准确的命名方式。

    合理准确的命名比注释强一百倍。

    相反,如果一段代码,相同技术水平的人需要配合你写的大量注释才能看懂,
    那你得好好反思一下,是不是你写的太烂了。
    vcn8yjOogEL
        5
    vcn8yjOogEL  
       3 天前
    如果你认为那些代码永远都不会被更改, 可以不写
    KimiArthur
        6
    KimiArthur  
       3 天前 via Android   ❤️ 4
    @iintothewind 注释应该是为了解释为什么的,而不是是什么。比如某段的参数设置很特别,不留下注释解释原因,碰到任何变动都可能需要花很长时间理解当初为什么这么处理
    passive
        7
    passive  
       3 天前 via Android   ❤️ 4
    > 好的代码,不需要太多注释,

    但是需要为了不到 10 行的代码写个 wikipedia 条目:

    https://en.m.wikipedia.org/wiki/Fast_inverse_square_root

    有些“程序员”日常编写和维护的都是这类代码。
    orioleq
        8
    orioleq  
       3 天前 via iPhone   ❤️ 1
    注释不是特别有必要,变量名和方法名更重要,除非有些算法逻辑需要解释下,下次让你自己能快速看懂;
    commit message 要,养成好的习惯。我觉得是这是类似每天早晚刷两次牙类似的习惯。当然你不愿意遵守也没啥大不了的。
    spadger
        9
    spadger  
       3 天前
    非常直观的业务逻辑代码没必要写注释,但是涉及到一些比较复杂的算法,几个常量,几个公式,实际代码呈现可能很简单,如果时间长了没有注释就容易看不懂。
    xuanwu
        10
    xuanwu  
       3 天前
    取决于提交历史信息对是否重要吧。
    之前重现木兰时,每个提交都尽量实现一个粒度最小的语法功能点,而且悬赏任务有的就要参考某个特定 commit ,提交信息就很重要了。
    soul11201
        11
    soul11201  
       3 天前 via Android
    1. 生命周期能活多久
    2. 代码本身的易读性
    3. 逻辑本身的复杂度

    一般我都从这三个维度考虑
    Abbeyok
        12
    Abbeyok  
       3 天前 via iPhone
    我是写给 copilot 看的,这样它能帮我自动补充一些代码,省时省力
    nicaiwss
        13
    nicaiwss  
       3 天前 via iPhone
    现在没啥必要注释,ai 会自动生成
    lemoon
        14
    lemoon  
       3 天前
    方便回滚就行
    leonshaw
        15
    leonshaw  
       3 天前 via Android
    @iintothewind 如果写的代码都不需要注释,得反思一下是不是 CRUD 写太多了。
    z1645444
        16
    z1645444  
       3 天前 via Android
    注释帮助开发者加速恢复大脑里的上下文

    变化比较多的、逻辑复杂的块,写上,是省未来迭代这部分开发者的时间
    kakki
        17
    kakki  
       3 天前
    让 AI 写,然后自己简单修改一下。
    ksc010
        18
    ksc010  
       3 天前
    @KimiArthur 干什么 和 为什么我都有写
    尤其是这个函数是干什么的
    FrankAdler
        19
    FrankAdler  
       3 天前 via Android
    稍微复杂点的还是写吧,别哪天自己都看不懂了。
    sir283
        20
    sir283  
       3 天前
    还是要写一下,不然,就跟这个项目一样: https://github.com/MrsEWE44/J2ME-Loader ,我 fork 过来,项目里面没有一句注释,不得不根据 commit 重新捋一遍,然后再做一定的修改,使其更符合国人的操作习惯。
    dawangyezi
        21
    dawangyezi  
       3 天前 via iPhone
    对公的写详细一点。个人拥有的项目只写最关键的一些提示信息,别让自己忘了当时为啥这么做就行了
    IvanLi127
        22
    IvanLi127  
       3 天前
    好记性不如烂笔头。commit message 是帮自己想起来之前到底抽什么风做了这些改动。不写的话我感觉都没必要用版本管理。
    NoOneNoBody
        23
    NoOneNoBody  
       3 天前
    需求不变且认为当初写的已经是“最好”,就不需要

    但需求往往会变,特别是增加功能
    有个函数可以算 abcd 四个字段,初期对 c 没有需求,省算力求速度,c 可能就是以默认返回
    当增加功能需求变化,c 也需要了,就记不起这个函数是如何处理 c 的了,会以为以前一并计算了

    我最记不清的是数据类型
    gouflv
        24
    gouflv  
       3 天前 via iPhone
    记录的目的,首先是给未来的自己看的。所以如果自己都觉得没有看的需求,那写了也白写
    milzero
        25
    milzero  
       3 天前   ❤️ 1
    @Remember 你还是太乐观,只需要一个月,甚至一周就会了
    sharpy
        26
    sharpy  
       3 天前
    我现在用通义写 commit
    realpg
        27
    realpg  
       3 天前
    写 但是不会写的那么规范 过于简单的可以直接写 bugfix
    出问题时候遍历历史容易找得到
    我觉得需要复杂的写的时候 我甚至能写出长篇大论
    自己一个人开发就是自己掌握详略得当,该糊弄时候糊弄,不该糊弄时候写流水账都不为
    ixoy
        28
    ixoy  
       3 天前
    建议保持好 commit 习惯,可以多看看开源项目 commit ,他们都有统一的 commit 格式。
    leo72638
        29
    leo72638  
       3 天前 via iPhone
    一个人可以随意一点,能写就写,有些没什么可写的就不写
    iintothewind
        30
    iintothewind  
       3 天前
    @leonshaw #15 写 CRUD 确实不需要注释,
    但不是 CRUD 的代码却需要写太多注释才能让人看明白,

    毫无疑问, 这就是烂代码.
    iintothewind
        31
    iintothewind  
       3 天前
    @passive #7 严格来说, 这是 code tricks, 代码的奇技淫巧.

    没有冒犯的意思, 如果你以写这样的代码为荣, 我为你的 team member 感到遗憾.
    akira
        32
    akira  
       3 天前
    经常写个代码, 过了一周就想不起来为啥这么写了。。好特么多奇奇怪怪的特例需求
    rosu
        33
    rosu  
       3 天前
    虽然是个人项目,但是也需要回顾和重写,就需要参考 commit message 了。规范可以考虑使用:Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/

    如果想用 AI ,同时也是 Jetbrain IDEs 用户,可以考虑使用我开发的 AICommit http://aicommit.app/

    V 友通过 tg 、邮件联系我,获取半年激活码~
    caola
        34
    caola  
       3 天前
    我自己的项目是 注释写,commit message 不写
    xing7673
        35
    xing7673  
       3 天前 via iPhone
    注释不多写,commit 会写的比较详细
    cutchop
        36
    cutchop  
       3 天前
    注释 AI 写、单测 AI 写、commit AI 写......代码 AI 写
    passive
        37
    passive  
       2 天前 via Android
    @iintothewind 并不是 trick ,经过我和 team member 手里的代码里有许多这种“加了密”的函数,虽然精度要求会比这个例子高。

    科学计算上为了运算速度,尤其是 1980 年前后的代码,受到当时硬件的限制,几乎到处都是这样对精确结果的近似展开,没有注释或者论文就没法维护,总不可能每次都从头推导。

    全部 refactoring 成适合现代浮点硬件的“干净”代码需要的测试量太大,况且浮点结果的收敛和精确度有时候很玄学,工程上不现实,只能继续维护这些 legacy 代码,需要时在上面增加可选高阶修正项的补丁。
    memorycancel
        38
    memorycancel  
       2 天前
    RTFM

    写文档写注释是 unix 留下来的传统之一,利己(方便自己复习),利他。
    sampeng
        39
    sampeng  
       2 天前
    求求你们了。别再说好的代码不需要注释。这都是偷懒行为。到处都是 GetXXX 。猜都要猜半天。尤其是自己写的。你今天写这行函数方法和明天想同一件事可能命名就会不一样。歧义大得飞起。不写注释就是坑自己
    hingle
        40
    hingle  
       2 天前
    sing-box 也是个人维护的项目,基本不写注释,只写 commit 。
    layxy
        41
    layxy  
       2 天前
    要写,时间久了可能自己都忘了某些特殊场景为啥要这么干,而且这个项目不可能一直由你维护
    rrZ2C
        42
    rrZ2C  
       2 天前
    对公项目通常都有 task bug req 的 id 吧,基于这些写 msg 也容易

    个人项目经常想到一出是一出 失去自己预设的主轴
    CodeAllen
        43
    CodeAllen  
       2 天前
    别给自己挖坑,对于复杂的逻辑写好注释,commit 写好大概改了哪些功能。
    注释并不是每一行都写,一般是复杂的逻辑,或者需要特别注意的逻辑,比如执行先后顺序,后面自己再改代码也快。
    commit 写改动,比如写版本迭代描述的时候,导出 commit 就是实际工作内容。
    总之,养成好的习惯,不论什么项目都按照良好习惯来,不管是自己维护还是别人接手维护,都要好不少。
    mikawang
        44
    mikawang  
       2 天前
    如果上生产了,commit 还是要好好写,还在开发无所谓
    skallz
        45
    skallz  
       1 天前
    个人项目的话,我自己 commit 基本是不会写有用信息的,顶多带上版本号,主要是代码里面的注释感觉一定得有,不然真就只有上帝能看懂了。。。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2877 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 31ms · UTC 12:29 · PVG 20:29 · LAX 04:29 · JFK 07:29
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.