Comments in the source code

Question

How to keep source code well-documented / commented out? Is there a tool for creating a skeleton for comments on a Unix platform for C ++?

In general, how many comment lines are recommended for a file with approximately 100 lines of code?

Answer 1

As a rule, it is best to let the code itself explain what it does, while there are comments to explain why this is so. There are no numbers to stick with. If your 100 lines speak for themselves, don't comment at all or just provide a resume at the beginning. If there is any knowledge other than what the code does, explain this in a comment.

If your code is too complicated to explain, this may be a reason for refactoring.

Thus, when you change the implementation, you also do not need to change the comments, since your comments do not duplicate the code. Since the reasons for design rarely change, you can safely document them in the comments for clarity.

Answer 2

Personally, I think skeletal comments are a terrible, terrible idea. I understand that sometimes it’s nice to save a couple of keystrokes and maybe get the argument signatures in the comments ... but as a result of n + 1 empty useless comments (when the editor added the templates and the encoder left them as they are) it is simply more annoying.

I really think that comments are necessary, in any case, if only one code that is written is too trivial to explain, the likelihood that the code in question is useless (i.e. it could be automated and should not be written manually). I comment very well on my code because I found out that I usually need this first. That others can use them is just an added bonus.

Answer 3

In general, how many comment lines are recommended for a file with approximately 100 lines of code?

It’s enough that your intention is clear and explain any unfamiliar idioms. There is no rule of thumb because there are no two 100 lines of code.

For example, in C # a property can be set by setters and getters as follows:

public int ID { get; set; } 

Now I didn’t even see C # until I joined StackOverflow two weeks ago, but for me it does not require comments. Commenting on this,

 // accessor and setter for ID property 

it will be just noise. Similarly

 for( int i = m ; i < n; ++i) { // "loop from m to n" is a pointless comment char* p = getP() ; // set p to getP, pure noise. if( p ) // if p does not eqaul null, pure noise int a &= 0x3; // a is bitwise or'd with 0x303, pure noise // mask off all but two least significant bits, //less noisy but still bad // get remainder of a / 4, finally a useful comment 

Again, any competent coder can read the code to see what it does. Any coder with basic experience knows that if( p ) is a common idiom for if( p != 0) , which needs no explanation. But no one can read your intentions unless you comment on this.

Comment on what you are trying to do, your reason for this, and not what the code explicitly does.

When editing: you will notice that after 11 days no one commented on the intentional error in one of my comments for example. It just emphasizes that this comment is pure noise.

Answer 4

I think this question has many good relevant answers for a similar question: Self-documenting code

As for the tools for creating comments, it depends on the editor you use and on the platform. Visual studio automatically creates comment space, at least for C # sometimes. There are also tools that use comments to create documentation. As for the strings, I think this does not matter. Be as concise and clear as possible.

Answer 5

I think a good recommendation is to comment on each class and method with a general description of what everyone is for, especially if you use the HTML documentation tool. In addition, I try to keep comments in the comment code with minimal code, which could be potentially confusing, or require an interpretation of intent. Try writing your code so that it does not require comments.

I don’t think there really is a metric that you can apply to comments / lines of code, it just depends on the code.

Answer 6

My personal ideal is to write enough comments so that only reading the comments explains how and why the function is supposed to be used. How it works tends to come out of well-chosen variable names and a clear implementation.

One way to achieve this, at least on the comment side, is to use a tool like Doxygen from the start. Begin coding each new function by writing a comment describing what it is intended for and how it should be used.

Make sure that Doxygen is configured correctly, create the document generation as a build step and read the final documentation.

The only comment template that can be useful is the one that sketches at the very beginning of the Doxygen comment block, but even that can be too much. You want the generated documentation to explain what is important without cluttering it with useless placeholder text that will never be overwritten.

Answer 7

This is an item that can be taken to the extreme (like so many things these days). Adopting a strong policy can sometimes jeopardize the devaluation of the exercise (i.e. Comments for comments) most of the time, IMHO.

Sometimes a redefinition policy makes sense (for example, "all public functions must have comment blocks") with exceptions - why bother with the generated code?

Commenting should occur naturally - it should complement the reading code along with meaningful names of variables, properties and functions (etc.).

I don’t think there is a useful or accurate measurement of X comments on Y lines of code. You will probably get a good sense of balance through reviewing (for example, “this code here should contain a comment explaining its purpose”).

I'm not sure about automatic commenting tools for C / C ++, but the .Net equivalent should be GhostDoc. Again, these tools only help determine the structure of comments - meaning still needs to be added by the developer or those who need to interpret the point of code or design.

Answer 8

Commenting out the code is necessary if you automatically generate documentation (we use doxygen ). Otherwise, it is best to minimize it.

We use the skeleton for each method in the .cpp file.

 //************************************************************************************************** // /// @brief /// @details /// @param /// @return /// @sa // //************************************************************************************************** 

but this is only because of our documentation needs

Answer 9

The rules I'm trying to follow are:

• write code that is automatically documented: beautiful and understandable variable names, resist the temptation of smart hacks, etc. This tip depends on the programming language you are using: it’s much easier to follow with Python than with C.

• commentary at the beginning to guide the reader so that they know what they should expect.

• to comment, which is not obvious from the code. If you had problems writing a piece of code, it may mean that he notices a comment.

• The library API is a special case: documentation is required (and putting it in code is often a good idea, especially with tools like Doxygen). Just do not confuse this documentation, intended for users with one that will be useful for library developers.

• Comment on what may not be in the code, for example, policy requirements, which explain why everything is the way it is.

• Comment on the source information, such as a link to a scientific article that describes the smart algorithm that you use, or the RFC standardization of the network protocol that you implement.

• Comment on the hacks! Everyone sometimes has to use hacks or comment on this, but please be kind to a future maintainer, comment on this. Read " Technical Duty .

And do not comment on the rest. Quantitative rules such as “20% of lines” should be comments “clearly stupid and explicitly intended only for PHBs.”

Answer 10

I don’t know a single tool, but it’s always good for me to have some comments in the code if it is supported by someone else in the future. At the very least, it is good to have header blocks for classes and methods that describe what the class is intended for and what this method does. But yes, it’s good to keep comments as small as possible.

Answer 11

I prefer to use comments to explain

• what the class \ function should do
• what he should not do
• Any assumptions I make should be followed by users of the \ function class.

The following plugin is very useful for users of the vi editor. We can define patterns for class comments, function comments, etc.

connect csupport

Answer 12

There are no good rules in terms of comment / code ratios. It totally depends on the complexity of your code.

I follow one (and only one) rule regarding comments (I like to stay flexible).

The code shows how everything is done, comments show what is done.

Some code does not need comments at all, because of its obviousness: this can often be achieved by using good variable names. Basically, I will comment on the function, and then comment on the main blocks using the function.

I think this is bad:

 // Process list by running through the whole list, // processing each node within the list. // void processList (tNode *s) { while (s != NULL) { // Run until reached end of list. processNode (s); // Process the node. s = s->nxt; // Move to next node. } } 

as all you do is write code three times. I would prefer something like:

 // Process list (or rest of list if you pass a non-start node). // void processList (tNode *currentNode) { // Run through the list, processing each node. while (currentNode != NULL) { processNode (currentNode); currentNode = currentNode->nextNode; } } 

Answer 13

You guys can argue, but I really believe that:

Usually you do not need to write comments. Just like that. The code should be written in such a way as to explain itself, if it does not explain itself, and you must write comments, then something is wrong.

However, there are some exceptional cases:

• You must write something that is VERY mysterious in order to get performance. Therefore, here you may need to write some explanation.
• You provide a library for any other group / company. You better document its API.
• There are too many novice programmers in your organization.

Answer 14

I would not be so rude to say that comments are an excuse for poorly programmed code, like some people above, and not to say that you do not need them.

It also depends on your editor and how you like to see your code in it and how you want others to do it.

For example, I like to create areas in C #. Regions are called dumped areas of the code, in a sense commented out by code containers. So when I look at the editor, I actually look at the pseudo code.

 #region Connect to the database // .... #endregion #region Prepare tables #region Cache tables ... #endregion #region Fix column names ... #endregion #endregion 

This kind of code is more readable than everything I know, but, of course, it needs an editor that supports custom folding with names. (e.g. Visual Studio editor, VIM ...). Someone will say that you can achieve the same if you put the regions in the procedures, but firstly, you cannot always do this, and secondly, you need to go to the procedure to see its code. If you just set hotkies to open / smooth an area, you can quickly see the code in it while scrolling and reading text and, as a rule, quickly navigate the hierarchy of regions.

On line comments, it would be nice to write code that self-documents itself, but, unfortunately, this cannot be said in generall. It depends on the projects, its scope and complexity.

As a final note, I fully offer documentation in code using a portable and indepent language , for example, NaturalDocs , which can be created to work with any language around with natural syntax that does not include XML or any special formation (hence the name) , plus it does not need to be installed more than once.

And if there is a guy who does not like comments, he can always delete them with a simple tool. I even integrated such a tool into my editor, and the comments went through a simple click on the menu. Thus, comments cannot damage the code in any way that cannot be fixed very quickly.

Answer 15

I say that in general comments are a bad smell. But the built-in code documentation is great. I elaborated on this robowiki.net question:

Why comments are bad

Answer 16

I agree with everyone about self-documenting code. And I also agree with the need for special comments when it comes to creating documentation. A short comment at the top of each method / class is useful, especially if your IDE can use it for tooltips when completing the code (for example, Visual Studio).

Another reason for the comments that I did not mention here relates to types of unsafe languages ​​such as JavaScript or PHP. You can specify data types this way, although Hungarian notation can also help there (one of the rare cases of using it correctly, I think).

In addition, tools like PHPLint can use special type-related comments to check your code for type safety.

Answer 17

There are no indicators that you can reasonably use for comments. You should never say that x lines of code should have y comments, because then you will get silly useless comments that just recount the code, and this will degrade the quality of your code.

100 lines of code should have as few comments as possible.

Personally, having used them in the past, I would not use things like doxygen to document the internal code to the extent of each function and each parameter that needs labeled descriptions, because with well-designed code you have many functions and with good names, more often in total, these tagged descriptions do not say more than the parameter name.

Answer 18

My opinion is comments in the source code are evil. The code should be documented. Developers usually forget about reading and updating.
How sad Martin Fowler: “if you need a comment for a block of lines - just create a new function” (this is not a quote - this phrase, as I remember it).

It is better to keep separate documentation for utility modules, the basic principles of your project, the organization of libraries, some algorithms and design ideas.

Almost forget: I once used code comments. It was an MFC / COM project, and I leave links from MSDN articles to articles on non-trivial solutions / workarounds.

100 lines of source code - it should be clear, if not - it should be divided or reorganized into several functions, which will be more clear.

Is there a tool for creating a skeleton for comments on a Unix platform for C ++?

Vim has plugins to insert a doxygen comment template if you really need it.

Answer 19

Source code should always be documented where necessary. People claimed that and what did not document. However, I would like to add one more note.

Let's say I applied a method that returns a / b

So, as a programmer, I am a big citizen, and I will call the user what to expect.

 /** * Will return 0 if b is 0, to prevent the world from exploding. */ float divide(float a, float b) { if (b == 0) return 0; return a/b; } 

I know it is pretty obvious that no one will ever create such a method. But this may be reflected in other issues when API users cannot understand what the function expects.