5

I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the debugging stage of development. As I'm tracking down bugs, I'll run across a block that makes me think "hmm...that might confuse someone in the future. I'd better comment that", and I'll add the appropriate comments. All of my comments are done this way.

Is this an appropriate way of commenting? Should comments be written as the code is written? Or does it really matter when the comments are written, as long as they adequately explain why this block is used?

5
  • 13
    The correct way is to write code that does not need comments, but if code is complicated to need comments, then when its written is the time to add them.
    – Ramhound
    Commented Nov 19, 2012 at 19:19
  • 7
    I recommend reading “Clean Code”.
    – Gallaecio
    Commented Nov 19, 2012 at 19:30
  • 7
    I'm half-repeating a lot of the answers here, so I won't make this a whole new answer, but the best time to write a comment is while you still remember why you're writing the code you're writing. A month, a week or even a day later you might not remember what was going on that forced you down a particular route.
    – Gareth
    Commented Nov 19, 2012 at 19:42
  • 3
    Keep in mind that there are (at least) 2 kinds of good comments. One kind is inline comments, written to elucidate otherwise confusing code, hopefully rarely. Another kind is documentation comments on your that are picked up by the IDE or documentation generation tool, which allows better intellisense and descriptions of what a method does (as well as pre/postconditions). The lifecycle of these kinds of comments is usually quite different
    – Chris Bye
    Commented Nov 19, 2012 at 21:51
  • 1
    So what do you do when you come across a block that makes you think: "Cripes! What the heck was I thinking? I don't remember being drunk at work in the past week..."?
    – Caleb
    Commented Nov 19, 2012 at 22:26

7 Answers 7

Reset to default
19

Code should be self-describing, whenever possible. In other words, if you write clear code, you will need fewer comments.

Comments should include:

  1. A general description of the class/method and what it does,
  2. How objects and methods relate to each other, as an overall architecture.
  3. Anything that is not immediately obvious from reading the code, such as obscure performance optimizations.

In general, comments should be written when they are needed, which ideally is when you write the code that requires them.

Avoid comments that state the obvious, or restate what is already clear in the code. The more comments you have, the more comments you will have to maintain when you change the code.

7
  • 11
    +1 I would add the common distinction of comments should answer why your code is doing something, not generally what it's doing. You're skirting about it and the answer is good, it's just a good direct-to-the-point concise way of remembering when to comment or not to.
    – Jimmy Hoffa
    Commented Nov 19, 2012 at 20:43
  • Agree with @Jimmy - What the code does is defined by the language specification, there should be no need to comment it. However, the harder the What is to understand, the more likely it is defective, and less likely any developer can tell what was intended. Simple example 'x = a+bc' - we can all work out that it is (in most languages)'a+(bc)', but if I know Why, and it is supposed to be x=(a+b)*c, I have a chance of spotting the bug. If you feel the need to comment the What, much better to fix the code (in this case put in the braces).
    – mattnz
    Commented Nov 19, 2012 at 22:25
  • 1
    @Omega: They are making you do this because they want you to get into the habit of writing clarifying code comments (which isn't a bad thing), and they want to know if you understand the code you are writing. In other words, you are "showing your work," like the math students must show all of the steps they are taking to solve their equations.
    – Robert Harvey
    Commented Nov 19, 2012 at 23:12
  • 1
    @RobertHarvey sadly I've spoken to quite a few folks who think you should be writing a great deal of comments in your code all the time. Usually these are people who have difficulty reading the code itself. That said, I wouldn't be surprised if there are professors who teach that lots of comments are good and only bad code lacks tons of detailed comments.
    – Jimmy Hoffa
    Commented Nov 20, 2012 at 0:00
  • 1
    @JimmyHoffa: It's even worse than that. All too often, folks ask programming questions on SO that have to do with some assignment that a teacher has given to his students, an assignment that clearly illustrates that the teacher has never actually done any real-world programming.
    – Robert Harvey
    Commented Nov 20, 2012 at 0:02
8

I'd rather suggest anyone writing comments from the beginning of development, since the rationales and the context are fresher in the mind. This will save you a considerable maintenance effort, since recollecting such intents can be exponentially difficult as the time passes on.

There are several rules of thumb for commenting the code, I keep an abbreviated list for practical usage.

  1. be succinct on telling what's being done
  2. leave the how it's being done to the code, only commenting the non-obvious stuff or general methodology (like referencing a well-know solution, algorithm or relationship)
  3. whenever you need to justify a non-idiomatic usage of the language (usually performance tricks require that)

All these items are better noticed by a proper peer-review process.

6

Write comments as you write the code. They're there for your benefit as well as the benefit of anyone who may be subsequently reading the code.

You've got things half right when you talk about "explain why this block is used" but the debugging stage is just going to be too late for that. If you have to think about why you wrote things a certain way at this later stage, then you're already in a position where a comment written while writing the code would have saved you time and trouble.

They also serve to help you focus your mind while coding; rather than rushing ahead with something they force you to stop for a short while, think a little more about what you're doing now, and can prevent you from going down a wrong track.

None of this is to say that while you're writing the code is the only time you should write comments. If, during any later stage (not just debugging) it seems appropriate to add a further comment, modify an existing one or add a new one where there wasn't one before (or even remove one that now seems unnecessary), then do so too.

3

Ideally, comments should be written at the same time as the code.

In the real world, those comments are not nearly as often as needed actually written, so if you stumble across a piece of code that, in your opinion, deserves an additional comment, there should be nothing against adding it later (or commenting upon it if you found it during a review).

2

Most often I write comments before and instead of code. This way I lay out a plan of the future code in high-level terms.

Then, I add code that the comments suggest. Comments describe what and why is done, code adds the how.

After that, some comments may be redacted, if code is transparent enough; some (much fewer) comments need to be expanded.

This way, I rarely have to add comments to existing code.

1

Your method will work great IFF every piece of code you write gets thoroughly debugged and you have many passes through it to comment it. Hopefully, you will one day write more code that works fine (more-or-less) on the first try. Which means fewer or no long debugging sessions, which means fewer or no or comments, if you strictly follow a "comment only when debugging rule".

I would say write the comments as you write the code. If you write code that you think might require extra explanation, write the comments as soon as you realize they might be needed!!

(and yes, you will need to update your comments if your code changes in such a way that the comments are no longer valid)

1

Comments can be written at any stage, comments SHOULD be written when you believe the code needs explanation and you know that you understand it.

Believing the code needs explanation should almost always be based upon your belief about how easy it is to understand the purpose of the code -- if the purpose is clear, then you probably don't need an explanation as to what it is doing. This is in part the purpose of good naming -- so that given a name of a function and it's input/output, you will understand why the code is needed and why it is doing whatever it is doing.

Comments on the syntax should be extremely rare, pretty much limited to cases where it is BOTH obscure AND possible to misunderstand it to be something else. If it's simply obscure, then trust that they will look it up if they need it, if it's simply likely to be misunderstood a + b * c then write it so that it's less likely to misunderstand a + (b*c). If on the other hand the purpose is unclear (working around a framework/compiler bug for an extreme example) then you need a comment so that the next person can understand why you are doing what you are doing.

Adding comments when you debug is fine, debugging naturally brings you back to older code which you may struggle to understand -- and struggling to understand, you know that it needs comments.

This may be why lots of people start off giving comments on syntax -- they haven't yet mastered it, and are still struggling with it a bit, and don't have enough experience to realize that syntax is something that they will learn and understand later. They expect to have trouble understanding the syntax, and thus provide a comment.

But having this as your normal mode of operation is not ideal, at best it is then helpful the 2nd time you have to debug that code. You should strive to anticipate where you will have trouble understanding the code, and write the comments explaining it as it is written. Don't expect to get it right all the time, or even most of the time at first. Just try to do better.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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