How do I write in-code comments and documentation

问题:

I want to add documentation in my code by means of comment lines.
Is there any standard format for this?

For example, consider the code below:

class Arithmetic
{
    // This method adds two numbers, and returns the result.
    // dbNum1 is the first number to add, and dbNum2 is second.
    // The returning value is dbNum1+dbNum2.
    static double AddTwoNumbers(double dbNum1, double dbNum2);
}

For this example code, is there any better way of writing the comment lines?

回答1:

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);

回答2:

you can format your comments so later you can generate documentation. the most popular tool for this is DoxyGen

回答3:

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:

1. A few sentences before the procedure/function saying what it does.
2. A description of the values being passed into it.
3. If a function, a description of what it returns.
4. Inside the procedure/function, comments that split the code up into shorter tasks.
5. 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.

Refered from: here

回答4:

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.