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

你写开发日志吗?你是怎样写开发日志的?

  •  1
     
  •   Foolt · 2018-06-17 12:42:05 +08:00 · 6846 次点击
    这是一个创建于 2111 天前的主题,其中的信息可能已经有所发展或是发生改变。

    我自己做一个小项目,过去都没有写开发日志的习惯,现在逻辑代码越来越复杂,必须要有注释了,但是因为代码不加密不压缩不去注释,不准备在代码上写注释,准备写开发日志,把功能注释记录在日志上,而日志文件则一个月用一个 md 文件,保存在 OneDrive。

    想问大家写开发日志吗?你们是怎样写开发日志的?

    23 条回复    2018-06-18 22:13:39 +08:00
    kslr
        1
    kslr  
       2018-06-17 13:07:49 +08:00
    代码写注释
    写笔记
    git 记录
    Foolt
        2
    Foolt  
    OP
       2018-06-17 13:13:17 +08:00
    @kslr 你的笔记用什么格式,存在哪里?
    yanaraika
        3
    yanaraika  
       2018-06-17 13:43:27 +08:00
    代码注释、wiki 记录与 git 提交 /PR 是三个不同层次的东西。注释是实现层面的东西,直接写在代码里;整体架构介绍、部署方法、结构等写在 wiki 里;一项新功能 /开发目标的达成写在 pull request 里。上面这几项在 Github/Gitlab 之类的都能一站式完成,不要分散在别的地方
    msg7086
        4
    msg7086  
       2018-06-17 13:56:49 +08:00
    最近写的项目。
    注释是这么写的,所以开发日志就不写了,我个人觉得写了没意义。
    https://github.com/msg7086/rb1drv/blob/master/lib/rb1drv/onedrive_dir.rb

    不写注释是可以的,即代码就是注释。只不过我还没到那境界,不写注释的话很多写得乱的代码自己都会跟不上。
    kslr
        5
    kslr  
       2018-06-17 14:14:22 +08:00
    @Foolt #2 Evernote 重要的是方便随时打开写或者录音,保证思路
    Foolt
        6
    Foolt  
    OP
       2018-06-17 16:50:19 +08:00
    @yanaraika 知道是知道,但是个人自用的小项目,总是连注释都懒得写。
    Foolt
        7
    Foolt  
    OP
       2018-06-17 16:52:58 +08:00
    @msg7086 我越发感觉到开发日志的重要性,很多次代码变更是实践结果,不写不行,写多了影响代码可视化。
    Foolt
        8
    Foolt  
    OP
       2018-06-17 16:53:58 +08:00
    @kslr 我倒不用随时记录,我是打算当总结用的,把每次变更写得清清楚楚,方便以后查阅。
    crayygy
        9
    crayygy  
       2018-06-17 17:18:42 +08:00 via iPhone
    我个人比较喜欢写 wiki 和博客,在做完一个新功能以后把前后的需求和实现都记录下来(公司项目),这样每次 manager 找我要相关的资料的时候直接丢一个链接就好了
    smdbh
        10
    smdbh  
       2018-06-17 17:25:31 +08:00   ❤️ 1
    文档写的再好,代码乱得 1b 有什么用,改起来还是痛苦。不如想着把代码结构改明白了,之后看了就能尽快上手。
    Foolt
        11
    Foolt  
    OP
       2018-06-17 17:31:01 +08:00
    @crayygy 我的个人项目倒是没有别人要查,主要是我自己要用到。
    VDimos
        12
    VDimos  
       2018-06-17 17:40:50 +08:00 via Android
    还是要有自己的代码风格,一看就知道这里的意思那种。
    Foolt
        13
    Foolt  
    OP
       2018-06-17 17:40:55 +08:00
    @smdbh 我的代码挺简洁,一眼就能看出来这是干什么用的。但是代码只能干自己的活,并不能告诉下我当时为什么这么写啊。

    我这个项目运行快四年了,我现在充分意识到好记性不如烂笔头,日志相当重要。没有日志,第 N 次修改之后,看着已经面目全非的代码,你只知道这个代码是干嘛用的,很难想起这些年来踩过的坑都有哪些,有可能一不小心又踩一次。
    Foolt
        14
    Foolt  
    OP
       2018-06-17 17:42:23 +08:00
    @VDimos 看懂代码没问题,代码很简洁,我一直没注释就是因为不用注释代码也能看懂。然而,我最近做了比较大的修改才意识到以前没把踩过的坑记录下来是错误的,有的坑又重新踩了一次。
    renothing
        15
    renothing  
       2018-06-17 17:45:15 +08:00
    赞同 2 楼的,直接写在 git 日志里最好,写单独文档笔记大部分时候纯粹是因为当时偷懒不好好写 git log 的缘故。
    zjsxwc
        16
    zjsxwc  
       2018-06-17 17:50:26 +08:00 via iPhone
    我们是在 redmine 里的开发需求下,把业务逻辑也一起记录,然后开发时无脑干类似“填空”的体力活好了,然后写完代码在最后的合并提交的注释里也备注上这个 redmine issue 的 id,就可以追踪代码了,方便以后接手的人继续维护
    wweir
        17
    wweir  
       2018-06-17 17:54:01 +08:00 via Android   ❤️ 1
    大的设计写在 readme 里,小的设计写在关键函数上面,复杂的逻辑随手写注释,公用的包还可以专门写个 doc 文件。
    剩下的除了写专门做分享用的文档,没找到需要写开发日志的场景
    janus77
        18
    janus77  
       2018-06-17 18:07:25 +08:00 via Android
    记性不好,有写注释的习惯,不过也仅是在有坑的地方特别写一下。
    有人说「代码即是注释」,大部分情况下是可以的,不过如果有坑,那就需要写了。比如某个地方和其他的处理不一样,这种地方多了脑子是记不完的,为提醒自己也提醒后来的维护者,还是推荐写注释
    anotherlf
        19
    anotherlf  
       2018-06-17 18:33:45 +08:00 via Android
    不写注释可不是好习惯啊。
    harmy
        20
    harmy  
       2018-06-17 19:07:41 +08:00   ❤️ 1
    function lb() {
    vim ~/logbook/$(date '+%Y-%m-%d').md
    }
    coyove
        21
    coyove  
       2018-06-17 19:29:08 +08:00   ❤️ 1
    东西记在 jira 里,git branch 按照格式填入 jira 号,devops+脚本会管理的
    hjdtl
        22
    hjdtl  
       2018-06-17 20:19:14 +08:00
    先想功能,写下实现步骤加上图文注释。再写代码实现该功能。
    一种记录形式,相当于开发日志了。
    SingeeKing
        23
    SingeeKing  
       2018-06-18 22:13:39 +08:00


    日志。。比如这个?
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   964 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 21:44 · PVG 05:44 · LAX 14:44 · JFK 17:44
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.