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

程序员们,大家喜欢写文档吗?

  •  
  •   liyiming2002 · 2023-07-28 11:25:32 +08:00 · 3622 次点击
    这是一个创建于 482 天前的主题,其中的信息可能已经有所发展或是发生改变。

    文档之于程序员,是很矛盾的事情。程序员非常不喜欢写文档,但又非常讨厌别的程序员不写文档。

    朋友们可以关注下我的个站:www.icodebook.com

    公众号:漫话软件设计。

    《漫画程序员涛哥》会在公众号及个站第一时间更新。欢迎大家关注~

    往期漫画:

    《改个 Bug 要多久?大家有没有过于乐观被打脸的经历》

    《程序员错觉之出差下周就回来》

    《假如让程序员去换灯泡》

    〈程序员错觉之这个需求两天搞定》

    1.jpg 2.jpg 3.jpg 4.jpg 5.jpg 4 2.jpg

    我觉得推崇“代码即文档”外,一些必要的设计文档也是必不可少的。另外也不能完全迷信代码的文档能力,这需要较高的水平和经验。一些关键业务的代码可能也需要配以文档。但文档不宜过细,否则需要频繁改动,但是无人维护就会过时。

    31 条回复    2023-07-29 19:05:18 +08:00
    brader
        1
    brader  
       2023-07-28 11:27:18 +08:00   ❤️ 1
    让我写文档的我都是觉得有病
    sankooc
        2
    sankooc  
       2023-07-28 11:36:07 +08:00
    java 程序员真不需要写文档 特别是 springboot 写不出什么花样
    LxnChan
        3
    LxnChan  
       2023-07-28 11:36:54 +08:00   ❤️ 1
    最不喜欢两件事:
    1.不写文档的人
    2.写文档
    xudaxian520bsz
        4
    xudaxian520bsz  
       2023-07-28 12:25:12 +08:00
    文档要实时,数据库中的字段要有描述,接口需要通过工具生成文档,反正我是用 apipost --> runnerGo ,香
    yolee599
        5
    yolee599  
       2023-07-28 13:09:33 +08:00 via Android
    写啥文档,doxygen 直接生成
    opengps
        6
    opengps  
       2023-07-28 13:47:45 +08:00 via Android
    我喜欢为优秀的接口设计写文档,这种文档本身极其需要技术水平
    我讨厌那些繁琐的接口文档,重复量太大
    AoEiuV020JP
        7
    AoEiuV020JP  
       2023-07-28 14:02:11 +08:00
    一次性的不需要更新维护的文档我倒是不介意写,
    elechi
        8
    elechi  
       2023-07-28 14:05:59 +08:00
    挺喜欢写的,只要时间充足
    janwarlen
        9
    janwarlen  
       2023-07-28 14:12:13 +08:00
    只要给我时间,我甚至想画流程图...
    cedoo22
        10
    cedoo22  
       2023-07-28 14:21:05 +08:00
    自从用来 copilot, 写文档 反而效率更高 :)
    star7th
        11
    star7th  
       2023-07-28 14:22:23 +08:00
    在这里顺便推荐一个很方便写文档的工具

    为的就是解决这些麻烦

    https://www.showdoc.com.cn

    帮助介绍: https://www.showdoc.com.cn/help
    cndydb
        12
    cndydb  
       2023-07-28 14:47:24 +08:00
    正在写····
    huangqihong
        13
    huangqihong  
       2023-07-28 15:03:08 +08:00
    最不喜欢两件事:
    1.不写文档的人
    2.要我写文档的人

    现在出差去培训,要写项目周报,写培训文档,写反馈意见表
    honmaple
        14
    honmaple  
       2023-07-28 15:06:00 +08:00
    曾经在某事业单位遇到过五天时间,只给一天开发和测试,剩下四天不是在写文档的路上,就是在对文档和改文档的路上。嗯,对的是字号大小,改的是流程图颜色,具体内容提不上嘴,反正要突出一个参与感。。。
    csw3983931
        15
    csw3983931  
       2023-07-28 15:15:12 +08:00
    想问一下这种漫画是怎么做的,能具体讲讲不 ? @liyiming2002
    coder1741
        16
    coder1741  
       2023-07-28 15:17:50 +08:00
    不喜欢 写文档的都爬
    hzz2
        17
    hzz2  
       2023-07-28 16:57:15 +08:00
    给时间就写,不给时间就不写
    Orenoid
        18
    Orenoid  
       2023-07-28 17:02:34 +08:00
    喜欢,但要给时间
    hpu423
        19
    hpu423  
       2023-07-28 17:43:56 +08:00
    现在大环境写文档,不怕被裁?
    chengkai1853
        20
    chengkai1853  
       2023-07-28 18:30:00 +08:00
    都 Ai 时代了,让它去写
    edisonwong
        21
    edisonwong  
       2023-07-28 19:00:41 +08:00
    写文档我排期排一天,我能 2h 写完。就是评审的时候,提一堆无关紧要问题,明明文档里有写,突出一个参与感... 以前噼里啪啦快敲一顿文字,现在画流程图、架构图各种图画得不亦乐乎,用图说话,有好的技术建议也很欢迎,不仅自己思路开阔,还能继续回去改,继续占 pd
    edisonwong
        22
    edisonwong  
       2023-07-28 19:01:53 +08:00
    如果不给时间或者压缩我开发时间,那只能随便写,尽可能少暴露细节。。不然又引起一堆无谓争议,来回开会拉扯
    xiangbohua
        23
    xiangbohua  
       2023-07-28 19:41:16 +08:00
    说实话,我还挺喜欢写文档的,比如说方法的注释,我喜欢把方法的注释写的很清楚,比如参数怎么传、要注意什么、返回值含义是什么、是不是允许空之类的。
    当然,设计文档的话,我写的比较少,主要是不太会整理格式,
    xiangbohua
        24
    xiangbohua  
       2023-07-28 19:43:17 +08:00
    看到还有一句话,代码及文档的,我也是比较喜欢推崇这个。功能的实现我喜欢个方面控制的比较死,尽量保证实现的人只要按照接口要求实现就不会出什么问题的这种,但是感觉文档还是需要写的。
    xiangbohua
        25
    xiangbohua  
       2023-07-28 19:44:21 +08:00
    @opengps 对对对,特别是一些方法,明明就是 getEntity 非要写一个“获取数据库实例”这种就觉得没有必要
    Otho
        26
    Otho  
       2023-07-28 19:58:32 +08:00
    不喜欢,但是尽量写
    liyiming2002
        27
    liyiming2002  
    OP
       2023-07-28 22:54:27 +08:00
    @honmaple 你的情况属于主次颠倒了。。。。。。代码写的漂亮基本不用非常详细的文档。不过概要设计文档、架构文档我感觉还是需要的
    liyiming2002
        28
    liyiming2002  
    OP
       2023-07-28 22:55:17 +08:00
    @csw3983931 漫画是我用 ipad 画的。以后不知道是不是可以 ai 做了,哈哈!
    liyiming2002
        29
    liyiming2002  
    OP
       2023-07-28 23:04:21 +08:00
    @edisonwong 如果不给时间,那就是白嫖文档。坚决抵制!
    746970179
        30
    746970179  
       2023-07-29 10:54:33 +08:00
    文档不了解, 但是注释有点个人见解

    不要写代码做了什么( 不要去翻译代码 )
    而是写我要做什么( 结合业务, 说明想实现的逻辑 )

    比如 python 的一段代码, a_set & b_set
    不要写 找出 a_set 和 b_set 的交集, 或者 找出 a_set 和 b_set 的重复数据
    而是结合业务, 写 两个店铺都出单的产品
    liyiming2002
        31
    liyiming2002  
    OP
       2023-07-29 19:05:18 +08:00
    @746970179 代码能看懂的不用写注释。能用代码代替注释的尽量通过代码的结构和命名来代替注释。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1804 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 16:28 · PVG 00:28 · LAX 08:28 · JFK 11:28
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.