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

开源一个注释的规范, 使得代码像 Markdown 一样清晰

  •  
  •   mzer0 · 2015-12-23 16:48:05 +08:00 · 5277 次点击
    这是一个创建于 3018 天前的主题,其中的信息可能已经有所发展或是发生改变。

    https://github.com/mzer0-yu/CommentRules

    我规定了一些注释的类型:

    • 标题注释
    • 代码块注释
    • 警告型注释
    • 解释型注释

    ......


    二级标题:

    //
        // 二级标题 
    //
    

    三级标题:

    //
        //
            // 三级标题
    //
    

    平行代码块:

    /*---------------------------*/
    /*      Block Name Here      */
    /*---------------------------*/
    
          // Your Code Here
    
    /*---------End Block---------*/
    

    警告:

    //! Your Text Here
    //! Your Text Here
    //! Your Text Here
    

    解释:

    /*
    * Your Text Here
    * Your Text Here
    * Your Text Here
    */
    
    17 条回复    2015-12-24 15:21:29 +08:00
    harry890829
        1
    harry890829  
       2015-12-23 16:51:41 +08:00   ❤️ 1
    看到警告那部分,意思是?重要的事情说三遍?
    line
        2
    line  
       2015-12-23 17:58:20 +08:00
    谢谢
    jhaohai
        3
    jhaohai  
       2015-12-23 18:01:00 +08:00 via iPhone
    感觉不错的样子,每次写注释都是#~~
    unique
        4
    unique  
       2015-12-23 18:03:38 +08:00
    有没有 demo
    simple26
        5
    simple26  
       2015-12-23 18:51:35 +08:00
    单词似乎拼错

    2. Explaination --> Explanation
    vanxining
        6
    vanxining  
       2015-12-23 18:59:56 +08:00 via Android
    和 Doxygen 冲突了。
    Delbert
        7
    Delbert  
       2015-12-23 19:01:34 +08:00 via Android
    为啥不用 Doxygen 的规范?或者是楼主根本不知道……
    Delbert
        8
    Delbert  
       2015-12-23 19:02:47 +08:00 via Android   ❤️ 1
    Doxygen 是注释即文档
    firemiles
        9
    firemiles  
       2015-12-23 19:42:50 +08:00
    java 有 java style comment , qt 有 qt style comment ,而这些 style doxygen 都支持外加还有更多扩展语法,楼主这个格式实在是每什么用武之地。
    mzer0
        10
    mzer0  
    OP
       2015-12-23 19:44:24 +08:00 via iPhone
    @simple26 谢谢

    @Delbert
    @vanxining
    这个东西和 Doxygen 的目的、做法、效果都完全不一样,就像 Java 和 Javascript 一样。
    mzer0
        11
    mzer0  
    OP
       2015-12-23 20:27:59 +08:00
    @firemiles 难道你要每个人都用 Doxygen? 我只是把自己的注释规范开源了出来, 你想用就用, 不想用你可以用 Doxygen, 你也可以用自己风格的注释. 如果你只是看了两眼, 并觉得 Doxygen 和我开源的东西很像, 就声称我做的东西丝毫价值都没有, 那你和咸鱼有什么区别?
    stanhou
        12
    stanhou  
       2015-12-24 08:13:49 +08:00
    lz 几岁了?入行写程序几个月了?
    rogerchen
        13
    rogerchen  
       2015-12-24 10:20:39 +08:00
    楼主愿意分享自己的东西还是值得鼓励的,不过楼主的这个工作基本属于代码规范的制定,这种东西每个团队在开项目之前都会重新制定一份。而 Doxygen 不止是一套规范,还有一套完整的全自动文档生成工具链,更别说 Doxygen 的注释支持 Markdown , reStructured 等一大堆格式。

    短的来说,楼主这种自定义的代码规范在自己的小项目用用就行了。
    firemiles
        14
    firemiles  
       2015-12-24 13:48:04 +08:00
    @mzer0 不要激动,我并不是说你的格式不好,只是现有很多语言都有自己的一套注释规范,还附带文档生成工具,楼主如果要推广你的开源格式是比较有难度的,至少需要提供一些有竞争力的配套工具才比较好。
    mzer0
        15
    mzer0  
    OP
       2015-12-24 15:11:14 +08:00
    @rogerchen
    @firemiles
    这可能是因为你们对 C/C++项目的不了解. C/C++项目极少使用文档生成器, 多数注释是写在代码里的. CommentRules 的目的仅仅是提供一种清晰的排版方式, 和 Doxygen 的目的是完全不同的.
    mzer0
        16
    mzer0  
    OP
       2015-12-24 15:15:28 +08:00
    CommentRules 仅仅只是一种注释或代码的排版方式, 而 Doxygen 是一种用注释生成文档的工具, 两者的目的完全不同. 项目中不仅需要写注释, 还需要对代码进行排版, CommentRules 主要解决的是排版的问题, 而跟你写什么注释半点关系都没有. 另外我觉得 Doxygen 默认排版很难看.

    这就像你拿小刀和手枪对比一样, 难道有了手枪就不需要小刀?
    mzer0
        17
    mzer0  
    OP
       2015-12-24 15:21:29 +08:00
    最后说一句, 喜欢就用, 不喜欢就别用. 本来面向的就不是 Doxygen 的用户.
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1329 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 17:45 · PVG 01:45 · LAX 10:45 · JFK 13:45
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.