24

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice[1]:

Use comments sparingly! (I bet that's welcome.) Remember that program you looked through - the one with all the comments? How helpful were all those comments? How soon did you quit reading them? Programs are self-documenting, even assembler programs, with a modicum of help from mnemonics. It does no good to say:

LA B . Load A with B

In fact it does positive bad: if I see comments like that I'll quit reading them - and miss the helpful ones. What comments should say is what the program is doing. I have to figure out how it's doing it from the instructions anyway. A comment like this is welcome:

COMMENT SEARCH FOR DAMAGED SHIPMENTS

Should comments say why the program is doing what it is doing?

In addition to the answers below, these two Programmers posts provide additional insight:

  1. Beginner's guide to writing comments?
  2. An answer to Why would a company develop an atmosphere which discourage code comments?

###References

1. Programming a problem-oriented-language, end of section 2.4. Charles H. Moore. Written ~June 1970.

Improve this question
2

8 Answers 8

Reset to default
58

Should comments say WHY the program is doing what it is doing?

Unequivocally yes. There don't necessarily need to be many comments, mind you, but if you have them, WHY is the only question worth answering outside of a few bizarre fringe scenarios. The reasoning is simple. If I read your code, good or bad, I can see what the program is doing. I have no idea why. HOW seldom has anything I don't know. WHY is frequently based on history, weird portions of the problem domain, or hacks around third party dependencies.

Improve this answer
6
  • 4
    I agree mostly, except for "WHY is the only question worth answering outside of a few bizarre fringe scenarios". I don't think the bizarreness threshold is that high - sometimes a given block of code is just complicated and takes time to comprehend, and having a brief comment saying "this code basically does X" can help navigate code and mentally break it into components when you revisit it after forgetting everything (or when other people visit it the first time). Yes, you can refactor and make a nicely named method, but sometimes this ends up adding complexity to the code needlessly.
    – Superbest
    Commented Nov 1, 2012 at 12:19
  • 3
    HOW is, on very rare occasions, necessary. Exactly once in the past year and a half, I had to do something rather obscure and ended up putting the url to a StackOverflow question in the comment, which explained HOW that code works (yay language edge cases) using several paragraphs with code examples...
    – Izkata
    Commented Nov 1, 2012 at 14:20
  • 3
    When I see complicated code, I want to know WHY. Usually there's no reason except a lack of clarity from the original author. Occasionally it is complicated to work around bugs in underlying services, or for performance. In those cases a comment is invaluable.
    – kevin cline
    Commented Nov 1, 2012 at 17:03
  • 2
    @kevincline "WHY? WHY? WHY?" <- actual comment in a previous project ;)
    – yannis
    Commented Nov 2, 2012 at 10:38
  • 1
    Occasionally, a reference to a paper that explains the basic algorithm is nice (when it's otherwise utterly obscure). Sure, it might be obvious to someone who studied Analysis at PhD level, but that's miniscule proportion of the population of programmers!
    – Donal Fellows
    Commented Nov 3, 2012 at 17:28
18

Depends on what you mean by "why".

If you mean information like high level requirements, user stories, etc, then no, comments are not a good place to explain "why". A far better place would be your commit/push messages, which ideally should point to fuller explanations in tickets in your issue tracker. And obviously you can always have a comment in code pointing to the ticket.

If, on the other hand, you mean very short explanations of small but not obvious decisions you've made in your code, then such comments would be appropriate. But that's more or less the same as what Chuck Moore means by "WHAT the program is doing" (the "why" is implied).

Related questions:

Improve this answer
3
  • 6
    Commit messages have a problem: they can become detached from the code. Some of the code I maintain is over 20 years old and has source in it that dates virtually from the beginning of that period, yet the commit messages only go as far back as about 15 years ago (coupled to a botched move from SCCS to CVS before I started work with it). The second problem is that the code in question has had a lot of commits over the years; I'm not going to read that many commit messages and try to guess what part of the file they apply to.
    – Donal Fellows
    Commented Nov 3, 2012 at 17:37
  • 2
    Commit messages are fine to tell your current team WHY, but completely useless at telling the support developer in three years. Are people in the future supposed to scour commit messages?
    – Kirk Broadhurst
    Commented Nov 5, 2012 at 5:50
  • 1
    A decent version control will often have a feature to tell you which commits have modified a specific line. So, yes.
    – Brian
    Commented Dec 30, 2013 at 13:56
5

I'm a strong proponent of the Single Responsibility Principle which lends itself well to method names that reveal WHAT they are doing. WHY is a little tougher. If the implementation is convoluted enough to the point that comments are needed to justify what's going on then it'll be difficult to contextualize, in the midst of subsequent execution calls, why a given piece of code is running. My preference is to leave the WHY to the user stories and keep the code granular enough that it can effectively comment itself.

Improve this answer
7
  • 1
    User stories won't cover the reasons for the selection of the algorithm, just the reason why the function is there in the first place.
    – Donal Fellows
    Commented Nov 3, 2012 at 17:30
  • Agreed, which is why IMO, any justification of any sort of WHY explanation belongs at a higher level. Teams should be able to trust that their teammates are choosing good algorithms, if not then the program's performance typically bears that out in poor performance and/or technical debt.
    – KodeKreachor
    Commented Nov 3, 2012 at 18:51
  • But at what higher level? Seems that documents outside of the code often get disconnected over time so that a different maintainer coming back to the code 10 years on may not know that a document even exists which has relevant background material like algorithm selection. Somehow information that is not linked to code seems to be at high risk of being forgotten. Which then suggests comments in the code itself.
    – Assad Ebrahim
    Commented Nov 5, 2012 at 3:02
  • Comments within the code all too often become outdated and unmaintained as the code changes over time, I stopped trusting comments within code quite some time ago after seeing so many instances of obsolete or plainly inaccurate comments. Certainly a personal preference but if you choose to do so then you owe it to your teammates and future developers of the code to ensure you maintain your comments in addition to your codebase, as well as reviewing them for accuracy. Regardless, I don't ever recommend taking a comment as gospel, the truth lies soley in the implementation.
    – KodeKreachor
    Commented Nov 5, 2012 at 3:52
  • @KodeKreachor using that same logic you may not even bother documenting it at all since the documentation is possibly outdated all the way up or down the chain. Your argument doesn't make sense.
    – ACase
    Commented Oct 14, 2013 at 19:55
4

Why can be a very powerful question to answer.

If you have trouble answering it yourself, then you are probably not thinking through your code design properly, and might need to rethink the motivation for your class/function/whatever. If you can answer the question why clearly and concisely, then your class will also probably be clear and concise.

Improve this answer
0
3

The essence of the advice is to write code for both the compiler and for people, and to not explain things that are expressed by the code.

Redundancy between the code and comments creates problems. When the two disagree, both are probably wrong. If you have to write it twice and read it twice, someone probably paid for it twice.

Among the answers, we have down votes for explaining how, and up votes for explaining what and why. I agree. Where comments that relate parts of the code, or perhaps explain rationale that can be used to make minimal, cohesive, and coherent classes would be a benefit. The who and when of code can be found in the source control system. Source control commit comments give us an understanding and correlation of the systems evolution toward its goals. Linked with a bug tracker can answer many why questions.

Scope and applicability are good topics for comments. If we are separating concerns the way we should, we should use naming and comments to guide future maintainers. Programming by contract, using assertions, and unit tests are all in the mix of clarifying the meaning and expected behavior of our software.

Improve this answer
3

The code itself is partly for computer, partly for humans (the names of methods and variables). But comments are exclusively for humans, either other person or yourself in the future (who will be a little different person then you currently due to properties of our memory). Any message for humans is valuable if it consists helpful information. If you explain WHY you're using a sorted list and not the hash then it is less likely that you rush into replacing ineffective code two years later just because you instantly see this opportunity

Improve this answer
2
  • 1
    Thanks for the response. So in your opinion then, should comments include justifications for design choices, e.g. the reasons why a particular design was chosen over reasonable alternatives?
    – Assad Ebrahim
    Commented Nov 1, 2012 at 6:05
  • @AKE, I think in ideal world yes. But it's always a compromise due to time constraints. Maybe embedding audio commentaries might be a useful alternative if implemented properly, for example GUID linking to an externally stored stream.
    – Maksee
    Commented Nov 1, 2012 at 14:23
3

Comments should explain aspects of the code that will not be immediately apparent to a programmer that is familiar with the language. The facilities provided by the language should then be used to minimise the number of comments that remain necessary.

Improve this answer
2

I will get flamed for this, but in my experience, the most of the time the answer is NO.

Food for thought:

  • You are writing an essay. You write a paragraph of text. Would you then write another paragraph explaining what the first paragraph is all about? Unlikely. Is programming that much different from writing essays or novels? Some writers (programmers) are good and some are bad. Book authors write for people, when programmers write for people and machines. I would argue and say that code is written for both people and machines, so most of the time there should be no need in commenting (describing) what it does.

  • Comments that you write are always useful and make sense, don't they? How about comments written by your colleagues? What do you think they think about comments that you write? I hate some of my colleagues' comments. I bet they are not fond of mine too. Good that I have stopped commenting everything.

  • Could you not refactor (rename, restructure, reuse and whatever else you need to do) your code in a way so that it doesn't need comments? Most of the time you can do that. If not, then please post few code snippets in comments or in your answer - it would be interesting for community to try and refactor it so that there will be no need for further comments.

  • Do you like maintaining unnecessary things? I don't. Most of the comments that I have seen in non-public APIs were unneccessary.

  • Often people comment something that's broken. It's broken. Class is a mess, it does ten different things. I'll just comment it and it'll make me feel less guilty. Each time something breaks, people will look at my comment and it will make them feel better. No it won't. Bad code needs to be fixed on a spot, not commented. If you don't do it right away, than it will haunt you or your colleagues later. Guess what they will think of you?

I have been a software engineer for few years now and I went from "comment everything" to "no comments at all". Having said that, I would:

  • Comment public API, or any piece of code that will be given to a third party, otherwise they will probably spam you with complaints and support requests.
  • Regular expressions.
  • Something that's really complex. With all the frameworks out there, I hardly ever come across something really complex.

One of the answers here states that without comments it's easy to see what the program is doing, as opposed to why it's doing it. Why something is being done doesn't belong in code. It should be in a separate document, SharePoint, blog, napkin, but not in code.

Improve this answer

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