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

想问一下大家平时写代码注释的习惯是怎么样的

  •  
  •   spoonwep · 2014-06-10 22:26:09 +08:00 · 4098 次点击
    这是一个创建于 2013 天前的主题,其中的信息可能已经有所发展或是发生改变。
    尝试过一边写代码一边写注释,感觉非常乱,有什么提高写代码注释效率的方法吗
    22 回复  |  直到 2014-06-12 11:54:19 +08:00
        1
    PrideChung   2014-06-10 22:44:48 +08:00   ♥ 5
    把写注释的时间用来起一个好的变量名
        2
    sandtears   2014-06-10 22:45:30 +08:00
    窝一般习惯是每次写到 if 或者 for 语句的时候写几句简短的注释,写完比较麻烦的逻辑之后写一点注释。

    至于那种对于整个函数、整个类的注释,就是某个参数干嘛的、某个返回值干嘛的的那些,一般是后期补的。
        3
    chmlai   2014-06-10 22:45:44 +08:00   ♥ 1
    把 stackoverflow 的地址贴上.
        4
    chairuosen   2014-06-10 22:47:03 +08:00
    不写注释....变量名自解释
        5
    yukirock   2014-06-10 22:47:40 +08:00
    先寫註釋或文檔,一邊寫一邊整理邏輯,最後再動筆寫代碼。
        6
    palmers   2014-06-10 22:49:06 +08:00
    喜欢 行注释 注释别人的代码就使用段注释
        7
    zhenghuiy   2014-06-10 22:53:43 +08:00
    @PrideChung 同意。但比较复杂的地方也会写一下注释
        8
    TankyWoo   2014-06-10 22:59:55 +08:00
    Clean Code里说过,大意是:

    写注释,因为自己的表达能力不够,无法用代码来表达意图

    当然,也不是说不能写注释,适当的写注释不会太多,应该也不会导致乱吧。
        9
    dorentus   2014-06-10 23:03:57 +08:00 via iPad
    写 TODO 的时候可能会写解释性的注释简述实现方法,实现完了就删掉了。
        10
    jsonline   2014-06-10 23:05:07 +08:00
    变量名+2048
        11
    hourui   2014-06-10 23:58:19 +08:00
    用同样的风格对齐就行了, 视觉上的排版一致性, 能直接影响到视觉快乐度.
    怎么排, 不用太在意, 排出风格, 排出个性即可.
        12
    akfish   2014-06-11 02:36:48 +08:00
    找个Code Doc的生成工具(如doxygen),然后按这个工具的格式撸注释,一般而言主要着重注释类、方法、参数等接口性质的东西,养成习惯后,代码写完,API文档也有了。
    具体实现代码也就在重要的地方意思下就行了,真的需要事无巨细详细说明的,还不如另外写design document。

    当然,如果编程语言是类似CoffeeScript这种的,可以试试literal programming的注释风格,注释比代码还多,更像是写篇blog,中间插入代码块。
    然后同样可以用工具生成页面,比如CoffeeScript的源代码全是这样搞的,生成的页面很清晰:
    http://coffeescript.org/documentation/docs/coffee-script.html
        13
    lm902   2014-06-11 04:40:05 +08:00 via Android
    用好的名字,例如用GetServerConfigurationInformation(credential, "usessl"),而不要用getconf(login, true)
        14
    lightening   2014-06-11 06:14:35 +08:00
    不写注释,看不懂的代码就抽象成一个方法,起个好名字。

    实在要说明,放在 git commit messages 里面。
        15
    yangff   2014-06-11 09:21:18 +08:00
    c++
    在class和namespace的"}"后面加上一个注释 " // namespace XXX" " // class XXX"
    别的基本没有了。。
        16
    jsonline   2014-06-11 09:21:33 +08:00 via Android
    @lm902 永远没有必要在变量名里加 information 等单词,因为所有的变量都是 information。
    同理永远不要用 flag 命名一个 bool,因为所有的 bool 都是 flag。
        17
    spoonwep   2014-06-11 10:24:25 +08:00
    @PrideChung
    @chairuosen
    @TankyWoo
    @jsonline
    @lightening
    有时候公司会要求写代码注释,而且还有比例和格式的要求……
        18
    spoonwep   2014-06-11 10:26:33 +08:00
    @yukirock 可以试试,我也比较喜欢有条有理一点
        19
    spoonwep   2014-06-11 10:28:30 +08:00
    @akfish 好像是个很棒的工具,感谢推荐~赶紧去尝试一下
        20
    spoonwep   2014-06-11 10:28:58 +08:00
    @lm902 这样好长啊
        21
    lightening   2014-06-11 15:40:07 +08:00
    @spoonwep 好吧,我们公司的 code style 要求尽量不写注释,除非有非要写注释的理由。因为注释很容易导致不一致(更新了代码,没更新注释)。
        22
    spoonwep   2014-06-12 11:54:19 +08:00
    @lightening 各个公司对注释的要求相差还真大
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2272 人在线   最高记录 5043   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.3 · 29ms · UTC 07:33 · PVG 15:33 · LAX 23:33 · JFK 02:33
    ♥ Do have faith in what you're doing.