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.

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:

• Beginner’s guide to writing comments?
• Best practices in comment writing and documentation
• Style and recommendations of commenting code
• Are More Comments Better in High-Turnover Environments?
• What should I put in comments while commiting to the Source Control?
• https://softwareengineering.stackexchange.com/questions/89871/reasons-to-not-add-comments-to-source-control-check-ins
• Why would a company develop an atmosphere which discourage code comments?

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.

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.

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.

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

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.

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.