Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
26  
I think you just answered your own question with: "I am finding it difficult to understand how the application works". That is THE argument that you are looking for :) –  e-MEE Sep 14 '11 at 21:12
7  
You describe a problem, and seem to have decided that comments are the correct solution. Have you considered all of the alternatives? –  blueberryfields Sep 14 '11 at 21:13
11  
@AngryBird, properly structured code, with good variable and method names, eliminates the need for nearly all comments. –  CaffGeek Sep 14 '11 at 21:21
3  
Good unit tests, showing how the code is supposed to be used, can make understanding a code base much easier. –  Bill Michell Sep 14 '11 at 21:37
3  
Developers who write code that is hard to read aren't likely to write useful comments either. In fact it may make the problem worse if they use them as a crutch. –  JohnFx Sep 15 '11 at 13:20
show 8 more comments

8 Answers 8

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.

share|improve this answer
4  
Can you summarize some of the key points from the chapter here? –  Anna Lear Sep 14 '11 at 21:30
add comment

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.

share|improve this answer
1  
Some people would make the counterargument that if you want to see how to use the system (how it pieces together), look at the unit tests. To which other people might say "unit tests?" –  Anthony Pegram Sep 14 '11 at 21:36
1  
@Anthony: Agreed, unit tests are great for documenting your expectations for a method's behavior. But unit tests don't always adequately answer the question, "Why is this method here, and what is it used for?" –  Robert Harvey Sep 14 '11 at 21:44
1  
Nice summary (+1). Personally, I find clarification of why I decided not to use another alternative (method/datastructure/technique) most important. –  DaveFar Sep 14 '11 at 21:56
    
+1 for a great answer, except that I would restrict the last sentence with "comments should describe what each nontrivial public member does and how to use it", i.e. trivial getters and setters usually need no comments. Of course, I have no problem with comments on those once all the other, nontrivial methods are correctly commented. I am working on a legacy system where most of the existing comments are either autogenerated or otherwise contain absolutely zero useful information, like "Sets the value of the property X" on the method setX... aaargh –  Péter Török Sep 15 '11 at 8:14
    
@Péter: I assume that any public member is non-trivial. –  Robert Harvey Sep 15 '11 at 14:08
show 3 more comments

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.
share|improve this answer
1  
In general, methods should not have side effects. –  CaffGeek Sep 14 '11 at 21:41
    
@Chad: are you speaking of Haskell? –  DaveFar Sep 14 '11 at 21:51
2  
@user750378, I'm speaking of every language. If I call a method named "performThisTask" it should only be doing "ThisTask", nothing else. There should be no side effects that need to be documented. –  CaffGeek Sep 14 '11 at 21:55
    
oh, ic. So a method should not have any side effects that are not obvious. –  DaveFar Sep 14 '11 at 22:02
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.