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

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 3250 天前的主题，其中的信息可能已经有所发展或是发生改变。

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

here

Text

注释

your

17 条回复 • 2015-12-24 15:21:29 +08:00

harry890829

2015-12-23 16:51:41 +08:00

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

line

2015-12-23 17:58:20 +08:00

谢谢

jhaohai

2015-12-23 18:01:00 +08:00 via iPhone

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

unique

2015-12-23 18:03:38 +08:00

有没有 demo

simple26

2015-12-23 18:51:35 +08:00

单词似乎拼错

2. Explaination --> Explanation

vanxining

2015-12-23 18:59:56 +08:00 via Android

和 Doxygen 冲突了。

Delbert

2015-12-23 19:01:34 +08:00 via Android

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

Delbert

2015-12-23 19:02:47 +08:00 via Android

Doxygen 是注释即文档

firemiles

2015-12-23 19:42:50 +08:00

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

mzer0

2015-12-23 19:44:24 +08:00 via iPhone

@simple26 谢谢

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

mzer0

2015-12-23 20:27:59 +08:00

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

stanhou

2015-12-24 08:13:49 +08:00

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

rogerchen

2015-12-24 10:20:39 +08:00

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

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

firemiles

2015-12-24 13:48:04 +08:00

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

mzer0

2015-12-24 15:11:14 +08:00

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

mzer0

2015-12-24 15:15:28 +08:00

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

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

mzer0

2015-12-24 15:21:29 +08:00

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