What are the benefits of using comments

Question

I just accepted a new job. Our application is in the 50,000 lines of code area. None of which is commented. I am finding it difficult to understand how the application works. Id like to prevent this for the next person that joins the project by getting the team to start to use comments.

Forget about if you support comments or consider them code duplication. What are some of the benefits of using comments that I can use as reasons for the team to start using them. What arguments are there in favor of comments (Not looking for opposing arguments). Are there any publications or studies done that show that using comments improves code quality or something like that?

Answer 1

Clean Code has a whole chapter on comments, when they're good and when they're not. Also a lot of practical advice on how to write code that doesn't need so many comments.

Edit: Anna asked for a summary, and since you were asking only for pro-comment reasons, the table of contents level summary of good reasons to use comments from the book includes:

• Legal notices, like copyrights
• When you can't use a function name to explain something
• Your intent behind a decision
• Clarification of code you can't alter, like library call results
• Warning of consequences
• TODOs (to a reasonable degree)
• Amplify the importance of something seemingly inconsequential
• Javadocs in public APIs

There's a couple paragraphs or more on each of those topics, with actual code samples included for illustration. It really is a worthwhile read.

Answer 2

To the maximum extent possible, code should be self-describing. That is, it should be written clearly enough to be understandable without comments. This results in code that is more maintainable by others, and eliminates the redundancy that comments cause (when you change the code, you also have to update the comments).

However, comments are critical for describing the relationships between code objects and different parts of the system, and how to properly use your code once it is written. In other words, how all the pieces of your application or library work together. Developers who advocate writing no comments at all build large, opaque, indeciperable systems because they don't fully appreciate this point.

Uncle Bob Martin, in his book Clean Code, advocates using comments for the following purposes:

1. Explanation of Intent
2. Clarification
3. Warnings
4. Amplification
5. TODOs

At a minimum, comments should describe what each public member does and how to use it, and explain all parameters and return values with acceptable ranges (e.g. between 1 and 1000) for each.

Answer 3

When you analyze a piece of code you can't tell if it is correct or not unless you know what it is supposed to do. You can only tell what it does do. A good comment can tell you what the code is supposed to accomplish. If it is redundant, it is a good thing because it means the code is meeting it's objective.

Comments can also tell you why it does it.

'we kept lines under 128 bytes because there is a legacy component that breaks when they exceed that'

Someone who might argue 'put that in the unit test instead of a comment' fails to grasp that it then needs to be commented in the unit test, and that when someone changes the value and the regression test fails, he will discover that he wasted his time because the comment that he needed to see was in the wrong place.

Would you propose this?

'write_but_do_not_exceed_the_limits_that_the_legacy_component_can_handle()'

'Good naming suffices' is naive, an idea that comes from lazy people who never learned how to comment properly in the first place.

Answer 4

comments are not for how an application works, they are for why this function achieves its goals using X. If the code is poorly written and doesn't have function names that describe what they do, then adding a line for each function to do so would be a worthwhile use of comments as a band-aid. It sounds to me like you don't understand how to read the code if you can't understand how it works. If you meant what the code does, that should be explained in external documents like use cases or process flows and design diagrams. It also seems you are approaching learning the code from the wrong angle. Unless your code is in a single function that is 50000 lines long, length is irrelevant, it just gets you stuck on how big it is. You learn a large complex system in parts, pick a layer/class and learn what it does in relation to the project and how it works, then pick another and repeat. Its also helpful to work towards understanding the high level flow of what your app does, before trying to learn the low level implementation details.

Trying to enforce the use of comments for added code may end up being a worthwhile cause, but trying to go back and add comments to existing code is a pointless endeavor, it just doesn't work because the knowledge of what should be in those comments is gone because no one is in the mindset of the developer at that point in time.

Answer 5

Useful points of comments:

• Identify why there is a method to do X.
• Identify what are the inputs/outputs of a method so that it is clear if parameters should be tweaked,e.g. if passing in a number of milliseconds or seconds there may be adjustments to make.
• Identify side effects of a method,e.g. are there other things it does that one may want to know besides its initial intentions? (This should be rare of course)
• Put a note in the code that something has a "code smell" and is worth considering refactoring somehow.
• Put a note in the code to explain why a kludge was shoved into the place that it is, which is rather similar to the previous point.

Answer 6

One thing I haven't seen mentioned is not only the why you did something but a refernce to the bug tracking or project management system task number that made you make the change. Not for everything, but we have all been asked to make a change that there was a long involved decision making process (documented in the project management system) leading to what seems to to outsider to be an odd choice in the code but which the deverloper had complex reasons for doing that way or a change request we felt would come back to bite us later. Knowing right up front the task number to look up in the PM or bug tracking system can help immensely when later to see if the requirement has really changed or if the new requirement isn't taking the old requierment into account. I've gotten several bad future changes turned off because I was able to quickly find the reasoning behind why the application operated the way it did.

Answer 7

Have you thought on using Javadoc (or doxygen, or any other similar tool)? If so, you can use (also) the argument that it can generate an easy to consult reference of the applications APIs (and even diagrams) in HTML, that is accessible to everyone.

Also, unit testing and patterns to name methods, variables and others helps a lot.

Answer 8

Several answers have already been provided and more exist if you search this site. What I want to bring your attention to is as follows:

1. Before you ask people to do comments - Come up with a set of rules and examples of what comments should look like (format), length, content, scope and when to use them.

2. Avoid describing business rules inside the application as much as possible. Code may reference business rules in outside documents but should not verbally state them inside the code.