对于 C++ 来说，没有像 javadoc 这样的标准，但某些文档工具很流行并且常用。我突然想到 doxygen。
Doxygen 还支持熟悉的 javadoc 风格，即：
/**
This method adds two numbers, and returns the result.
@param dbNum1 is the first number to add
@param dbNum2 is second.
@return The returning value is dbNum1+dbNum2.
*/
static double AddTwoNumbers(double dbNum1, double dbNum2);
For c++ there isn't a standard, like javadoc, but certain documentation tools are popular and common to use. Off the top of my head, I can mention doxygen.
Doxygen also supports the familiar javadoc style, ie:
/**
This method adds two numbers, and returns the result.
@param dbNum1 is the first number to add
@param dbNum2 is second.
@return The returning value is dbNum1+dbNum2.
*/
static double AddTwoNumbers(double dbNum1, double dbNum2);
// This procedure moves the bullet upwards. It's called
//NUM_BULLET_MOVES_PER_SECOND times per second. It returns TRUE if the
//bullet is to be erased (because it hit a target or the top of the screen) and FALSE
//otherwise.
Boolean player_bullet::move_it()
{
Boolean is_destroyed = FALSE;
// Calculate the bullet's new position.
[Small chunk of code.]
// See if an enemy is in the new position. If so, call enemy destruction call and
// set is_destroyed to TRUE
[small chunk of code]
// See if bullet hits top of screen. If so, set is_destroyed to TRUE
[Small chunk of code.]
// Change bullet's position.
[Small chunk of code.]
Return is_destroyed;
}
You don't want to write too much. Suppose you write comments for a function that, in the future, saves you ten minutes of time understanding your code. Great. But suppose your comments are so verbose that it takes five minutes to write them and then, later, five minutes to read them. Then you've saved yourself zero time. Not so good.
You don't want to write too little, either. If code goes on for a page or two without something breaking down what's going on, well, I hope that code is clear as crystal, because otherwise you're wasting future time.
And you don't want to comment in stupid ways. When people first start writing comments, they often get hyper and write things like:
// Now we increase Number_aliens_on_screen by one.
Number_aliens_on_screen = Number_aliens_on_screen + 1;
Uhmmm, duh. If something is so obvious, it doesn't need a comment. And if your code is such a tangle that you need a comment for every single line of it, you'd probably profit from making it simpler in other ways first. Comments don't just save time, they cost it. They take time to read, and they spread out the actual code on the screen, so you can have less of it on your monitor to inspect at one time.
And, while we're at it, don't ever do this:
Short get_current_score()
{
[insert a whole bunch of code here.]
return [some value];
// Now we're done.
}
Oh? We're done? Thanks for letting me know. That big right bracket and the infinite expanse of empty space beyond really didn't tip me off to that. And you don't need a comment before the return statement saying, "Now we return a value," either.
So, if you are writing code, in the absence of a boss or a company policy telling you what to do, how do you comment it? Well, what I do for code I am stuck with maintaining myself is write an introduction. When I return to a procedure I forgot that I wrote, I want to see an explanation for what is going on. Once I understand what the machinery is doing, it becomes infinitely easier to understand the actual coding. This generally involves:
A few sentences before the procedure/function saying what it does.
A description of the values being passed into it.
If a function, a description of what it returns.
Inside the procedure/function, comments that split the code up into shorter tasks.
For chunks of code that seem thorny, a quick explanation of what is happening.
So we need a description at the beginning and a few signposts inside explaining the road taken. Doing this is very quick, and it saves a ton of time in the long run.
Here is an example from the theoretical Kill Bad Aliens. Consider the object representing the bullet the player fires. You will frequently have to call a function to move it upwards and see if it hits anything. I would probably code it something like this:
// This procedure moves the bullet upwards. It's called
//NUM_BULLET_MOVES_PER_SECOND times per second. It returns TRUE if the
//bullet is to be erased (because it hit a target or the top of the screen) and FALSE
//otherwise.
Boolean player_bullet::move_it()
{
Boolean is_destroyed = FALSE;
// Calculate the bullet's new position.
[Small chunk of code.]
// See if an enemy is in the new position. If so, call enemy destruction call and
// set is_destroyed to TRUE
[small chunk of code]
// See if bullet hits top of screen. If so, set is_destroyed to TRUE
[Small chunk of code.]
// Change bullet's position.
[Small chunk of code.]
Return is_destroyed;
}
If the code is clean enough, this sort of commenting should be sufficient. And it will save plenty of time the dozen times I return to this function to fix a dumb mistake I made.
Doxygen and other similar tools can help with this. Basically you write comments according to some pre-defined style and from that HTML/PDF/etc. documentation is extracted.
发布评论
评论（4）
对于 C++ 来说，没有像 javadoc 这样的标准，但某些文档工具很流行并且常用。我突然想到 doxygen。
Doxygen 还支持熟悉的 javadoc 风格，即：
For c++ there isn't a standard, like javadoc, but certain documentation tools are popular and common to use. Off the top of my head, I can mention doxygen.
Doxygen also supports the familiar javadoc style, ie:
您可以格式化您的评论，以便稍后生成文档。最流行的工具是 DoxyGen
you can format your comments so later you can generate documentation. the most popular tool for this is DoxyGen
你不想写太多。假设您为一个函数编写注释，将来可以为您节省十分钟的时间来理解代码。伟大的。但是，假设您的评论非常冗长，需要五分钟才能写完，然后又需要五分钟才能阅读。那么你就节省了零时间。不太好。
你也不想写得太少。如果代码持续一两页而没有任何东西破坏正在发生的事情，那么，我希望代码像水晶一样清晰，因为否则你会浪费未来的时间。
而且你不想以愚蠢的方式发表评论。当人们第一次开始写评论时，他们经常会变得亢奋并写下这样的东西：
嗯，呃。如果某件事如此明显，就不需要评论。如果您的代码非常混乱，以至于您需要对其每一行进行注释，那么您可能会首先通过其他方式使其变得更简单，从而受益匪浅。评论不仅节省时间，而且还耗费时间。它们需要时间来阅读，并且它们将实际代码分散在屏幕上，因此您可以在显示器上一次性检查更少的代码。
而且，当我们这样做时，永远不要这样做：
哦？我们完成了吗？谢谢你让我知道。那个大右括号和后面无限广阔的空白空间确实没有让我注意到这一点。并且您也不需要在 return 语句之前添加注释“现在我们返回一个值”。
那么，如果你正在编写代码，在没有老板或公司政策告诉你该做什么的情况下，你如何评论它？好吧，对于我自己维护的代码，我所做的就是写一个简介。当我返回到一个我忘记了自己写的程序时，我想看到对正在发生的事情的解释。一旦我了解了机器正在做什么，理解实际编码就变得非常容易。这通常涉及：
因此，我们需要在开头进行描述，并在里面添加一些路标来解释所走的路。这样做非常快，从长远来看可以节省大量时间。
这是理论上《杀死坏外星人》中的一个例子。考虑代表玩家发射的子弹的对象。您经常需要调用一个函数将其向上移动，看看它是否碰到任何东西。我可能会像这样编写代码：
如果代码足够干净，这种注释应该足够了。当我多次返回此函数来修复我所犯的愚蠢错误时，它将节省大量时间。
参考自：此处
You don't want to write too much. Suppose you write comments for a function that, in the future, saves you ten minutes of time understanding your code. Great. But suppose your comments are so verbose that it takes five minutes to write them and then, later, five minutes to read them. Then you've saved yourself zero time. Not so good.
You don't want to write too little, either. If code goes on for a page or two without something breaking down what's going on, well, I hope that code is clear as crystal, because otherwise you're wasting future time.
And you don't want to comment in stupid ways. When people first start writing comments, they often get hyper and write things like:
Uhmmm, duh. If something is so obvious, it doesn't need a comment. And if your code is such a tangle that you need a comment for every single line of it, you'd probably profit from making it simpler in other ways first. Comments don't just save time, they cost it. They take time to read, and they spread out the actual code on the screen, so you can have less of it on your monitor to inspect at one time.
And, while we're at it, don't ever do this:
Oh? We're done? Thanks for letting me know. That big right bracket and the infinite expanse of empty space beyond really didn't tip me off to that. And you don't need a comment before the return statement saying, "Now we return a value," either.
So, if you are writing code, in the absence of a boss or a company policy telling you what to do, how do you comment it? Well, what I do for code I am stuck with maintaining myself is write an introduction. When I return to a procedure I forgot that I wrote, I want to see an explanation for what is going on. Once I understand what the machinery is doing, it becomes infinitely easier to understand the actual coding. This generally involves:
So we need a description at the beginning and a few signposts inside explaining the road taken. Doing this is very quick, and it saves a ton of time in the long run.
Here is an example from the theoretical Kill Bad Aliens. Consider the object representing the bullet the player fires. You will frequently have to call a function to move it upwards and see if it hits anything. I would probably code it something like this:
If the code is clean enough, this sort of commenting should be sufficient. And it will save plenty of time the dozen times I return to this function to fix a dumb mistake I made.
Refered from: here
Doxygen 和其他类似工具可以帮助解决此问题。基本上，您根据一些预定义的样式和 HTML/PDF/等来编写注释。文档被提取。
Doxygen and other similar tools can help with this. Basically you write comments according to some pre-defined style and from that HTML/PDF/etc. documentation is extracted.