C ++代码文档/注释 [英] C++ code documentation/annotation

问题描述

你好，


我想知道是否有任何指导方针或既定方法或

样式甚至脚本或程序来注释和记录C ++代码，

特别是方法标题和类。


我不一定要求像doxygen那样生成

的API您的代码中的HTML文档。这只适用于公共API

恕我直言。但是使用C ++

注释生成统一的类和方法注释将是一件好事。


如果没有这样的东西，我应该使用C ++注释自己编写

注释，要做什么布局是

常用和首选？是否有某种风格指南，例如

用于Java注释？


-

Matthias Kaeppler

Hello,

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.

I''m not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.

In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like e.g.
for Java annotations?

--
Matthias Kaeppler

推荐答案

Matthias Kaeppler写道：

Matthias Kaeppler wrote:

我想知道是否有任何指导方针或既定方式或
风格甚至脚本或程序注释和记录C ++代码，特别是方法头和类。


是的，有指导方针。脚本或程序实际上并没有太大的意义，因为他们无法弄清楚意图，而且无论他们能够获得什么，b
up，已经在代码中了。我不相信像


a ++这样的注释; //增加''a''


是任何值，但这都是自动注释器可以做的。

我不是必须要求像doxygen这样的东西，它会从你的代码中生成一个API HTML文档。这只适用于公共API
恕我直言。但是使用C ++
注释生成统一的类和方法注释将是一件好事。


通常它是。这些东西通常定义在通常称为编码样式文档的内容中。开发团队通常会发布

这样的内部消费。

如果没有这样的东西，我应该自己编写使用C ++的
注释评论，做什么布局是
常用和首选？是否有某种风格指南，例如用于Java注释的
？

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.
Yes, there are guidelines. Scripts or programs do not really make much
sense since they can''t figure out the intent, and whatever they can come
up with, is already in the code. I don''t believe an annotation like

a++; // increment ''a''

is of any value, but that''s all an automated annotator can do.
I''m not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.
And usually it is. Those things are usually defined in what is commonly
known as "coding style documents". Development groups usually publish
something like that for internal consumption.
In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like e.g.
for Java annotations?

我不相信有一种普遍接受的方式。这就像命名

类成员或函数一样 - 人们做他们认为正确的事情以及他们认为什么使用b $ b他们认为代码更具可读性，那些事情就像个人

作为那些想起来的人。


V

I don''t believe there is a commonly accepted way. It''s like naming of
class members or functions -- people do what they think is right and what
they think makes code more readable, and those things are as individual
as people who think those up.

V

Victor Bazarov写道：

Victor Bazarov wrote:

Matthias Kaeppler写道：

Matthias Kaeppler wrote:

我想知道是否有任何指导方针或既定方法或
样式甚至脚本或程序来注释和记录C ++代码，
特别是方法标题和类。

I was wondering if there are any guidelines or established ways or
styles or even scripts or programs to annotate and document C++ code,
especially method headers and classes.

是的，有指导方针。脚本或程序实际上没有多大意义，因为它们无法弄清楚它们的意图，而且无论它们能够提供什么，都已经存在于代码中。我不相信像

a ++这样的注释; //增加''a''

具有任何价值，但这都是自动注释器所能做到的。

Yes, there are guidelines. Scripts or programs do not really make much
sense since they can''t figure out the intent, and whatever they can come
up with, is already in the code. I don''t believe an annotation like

a++; // increment ''a''

is of any value, but that''s all an automated annotator can do.

我不是必须要求像doxygen这样的东西，它会从你的代码中生成一个API HTML文档。这只适用于公共API
恕我直言。但是使用C ++
注释生成统一的类和方法注释将是一件好事。

I''m not necessarily asking for something like doxygen, which generates
an API HTML doc from your code. This only makes sense for public APIs
IMHO. But generating uniform class and method annotations by using C++
comments would be a nice thing.

通常它是。这些东西通常定义在通常称为编码样式文档的内容中。开发团队通常会发布类似于内部消费的内容。

And usually it is. Those things are usually defined in what is commonly
known as "coding style documents". Development groups usually publish
something like that for internal consumption.

如果没有这样的东西，我应该自己使用C ++编写
注释评论，做什么布局是
常用和首选？是否有某种风格指南，如
，例如对于Java注释？

In case there is no such thing, and I should have to write the
annotations myself using C++ comments, what layout to do that is
commonly used and preferred? Is there some sort of style guide like
e.g. for Java annotations?

我不相信有一种普遍接受的方式。它就像是对类成员或函数的命名 - 人们做他们认为正确的事情以及他们认为使代码更具可读性的内容，而那些事情与那些人一样个性化想想那些。

V

I don''t believe there is a commonly accepted way. It''s like naming of
class members or functions -- people do what they think is right and what
they think makes code more readable, and those things are as individual
as people who think those up.

V

你如何评论你的方法定义？

当我使用Visual时Studio，我有一个宏从方法头生成一个

注释模板，看起来大致如下：


//方法名称：Bar :: foo

//返回类型：void

//说明：给吧台吧。

void Bar :: foo（）

{

// ...

}


当然描述必须手动填写，但是当

选中的函数头调用宏时，其余的是由VB宏自动创建的。


但是我现在使用Emacs，我还没有时间学习Lisp，

所以我现在不用任何宏。


-

Matthias Kaeppler

How do you comment your method definitions?
Back when I used Visual Studio, I had a macro generating a
comment-template from method headers, which looked roughly like this:

// METHOD NAME: Bar::foo
// RETURN TYPE: void
// DESCRIPTION: Foos a bar.
void Bar::foo()
{
//...
}

Of course the description had to be filled in manually, but the rest was
created by a VB macro automatically when the macro was invoked on the
selected function header.

However I use Emacs now and I haven''t found the time to learn Lisp yet,
so I don''t use any macros right now.

--
Matthias Kaeppler

Matthias Kaeppler写道：

Matthias Kaeppler wrote:

[..]
你如何评论你的方法定义？稀疏地。


稀疏。

当我使用Visual Studio时，我有一个宏从方法标题生成
评论模板，看起来大致相似这个：

//方法名称：Bar :: foo
//返回类型：void
//描述：Foos a bar。
void Bar :: foo （）
{
// ...
}

当然，描述必须手动填写，但其余部分由
创建在
选择的函数头上调用宏时自动生成VB宏。

然而我现在使用Emacs并且我还没有时间学习Lisp，
所以我现在不用任何宏。

[..]
How do you comment your method definitions?
Sparsely.
Back when I used Visual Studio, I had a macro generating a
comment-template from method headers, which looked roughly like this:

// METHOD NAME: Bar::foo
// RETURN TYPE: void
// DESCRIPTION: Foos a bar.
void Bar::foo()
{
//...
}

Of course the description had to be filled in manually, but the rest was
created by a VB macro automatically when the macro was invoked on the
selected function header.

However I use Emacs now and I haven''t found the time to learn Lisp yet,
so I don''t use any macros right now.

老实说，现在，你真的需要前两个部分的标题

评论？从函数声明中收集它真的很难

它的名字是''Bar :: foo''并且它返回''void''？


我会对我的函数进行评论，但主要是因为它们的某些方面不是明显的名称和/或参数类型/名称。示例


//将数据对象保存在文件中

//如果fname为0，则使用文件名数据成员保存在文件中

//如果给出文件名，则保存到另一个文件中

//如果重命名为true，则将fname存储为新文件名。

//

int data :: save（const char * fname / * = 0 * /，bool rename / * = false * /）

{

.. 。


（不，我没有一个名为''data''的课程，这只是为了说明）


有时候这个评论放在函数本身内部，在

第一个语句之前，我对此不太一致。


我们不使用Doxygen但是，所以我们在每个

函数之上都没有很好的标题（虽然我们可能应该这样）。


V

Honestly, now, do you really need the first two parts of the "header
comment"? Is that really so hard to gather from the function declaration
that its name is ''Bar::foo'' and that it returns ''void''?

I do comment my functions, but mostly if certain aspects of them are not
obvious from the name and/or argument types/names. Example

// saves the data object in a file
// if fname is 0, saves in a file using filename data member
// saves into a different file if filename is given
// if rename is true, stores the fname as the new filename.
//
int data::save(const char* fname /* = 0*/, bool rename /* = false */)
{
...

(No, I don''t have a class named ''data'', this is just for illustration)

Sometimes this comment is placed inside the function itself, before the
first statement, and I am not very consistent about that.

We don''t use Doxygen yet, so we don''t have nice headers above every
functions (although we probably should).

V

这篇关于C ++代码文档/注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！