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

[mzer0]

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
*/

[harry890829]

看到警告那部分，意思是？重要的事情说三遍？

[line]

谢谢

[jhaohai]

感觉不错的样子，每次写注释都是#～～

[unique]

有没有 demo

[simple26]

单词似乎拼错

2. Explaination --> Explanation

[vanxining]

和 Doxygen 冲突了。

[Delbert]

为啥不用 Doxygen 的规范？或者是楼主根本不知道……

[Delbert]

Doxygen 是注释即文档

[firemiles]

java 有 java style comment ， qt 有 qt style comment ，而这些 style doxygen 都支持外加还有更多扩展语法，楼主这个格式实在是每什么用武之地。

[mzer0]

@simple26 谢谢

@Delbert
@vanxining
这个东西和 Doxygen 的目的、做法、效果都完全不一样，就像 Java 和 Javascript 一样。

[mzer0]

@firemiles 难道你要每个人都用 Doxygen? 我只是把自己的注释规范开源了出来, 你想用就用, 不想用你可以用 Doxygen, 你也可以用自己风格的注释. 如果你只是看了两眼, 并觉得 Doxygen 和我开源的东西很像, 就声称我做的东西丝毫价值都没有, 那你和咸鱼有什么区别?

[stanhou]

lz 几岁了？入行写程序几个月了？

[rogerchen]

楼主愿意分享自己的东西还是值得鼓励的，不过楼主的这个工作基本属于代码规范的制定，这种东西每个团队在开项目之前都会重新制定一份。而 Doxygen 不止是一套规范，还有一套完整的全自动文档生成工具链，更别说 Doxygen 的注释支持 Markdown ， reStructured 等一大堆格式。

短的来说，楼主这种自定义的代码规范在自己的小项目用用就行了。

[firemiles]

@mzer0 不要激动，我并不是说你的格式不好，只是现有很多语言都有自己的一套注释规范，还附带文档生成工具，楼主如果要推广你的开源格式是比较有难度的，至少需要提供一些有竞争力的配套工具才比较好。

[mzer0]

@rogerchen
@firemiles
这可能是因为你们对 C/C++项目的不了解. C/C++项目极少使用文档生成器, 多数注释是写在代码里的. CommentRules 的目的仅仅是提供一种清晰的排版方式, 和 Doxygen 的目的是完全不同的.

[mzer0]

CommentRules 仅仅只是一种注释或代码的排版方式, 而 Doxygen 是一种用注释生成文档的工具, 两者的目的完全不同. 项目中不仅需要写注释, 还需要对代码进行排版, CommentRules 主要解决的是排版的问题, 而跟你写什么注释半点关系都没有. 另外我觉得 Doxygen 默认排版很难看.

这就像你拿小刀和手枪对比一样, 难道有了手枪就不需要小刀?

[mzer0]

最后说一句, 喜欢就用, 不喜欢就别用. 本来面向的就不是 Doxygen 的用户.