When I learned PASCAL programming at TU Budapest in 1986 there was a preprocessor developed specially for student code. It stopped the compilation process if the number of inline comments was less than the number of executable code. There was a rule: we had to have at least 50% of the code meaningful comments. 30 years passed and now we fight inline comments. Clean code purists evangelize not to have inline comments at all and have unit documentation (JavaDoc in case of Java) only on the interface. Anything else explaining the implementation has to be self explanatory from the code itself.
That time there were even tools that extracted inline comments into documentation partially including the executable code. Can you recall WEB and TANGLE? That time it seemed to be very exciting to have a language that can be compiled to TeX for documentation purposes and also to PASCAL so the code could be executed. After 30 years we can see that was a dead end street. We do not mix programming and documentation. We rather separate them.
What is the reason for the change of attitude? Computer scientists 30 years ago were “stupid”? Were they advocating something that was and is bad? Or was that good that time and it is good now? Is there something that radically changed in the world and we live in a different world?
I was thinking about this recently and came to the conclusion that the answer is: A bit of both. The word “stupid” is a bit harsh and rude, but stating that computer scientists did not know as much as they do today is agreeable. After all that is development. If the knowledge remained the same it would mean we are at the point where we were 30 years ago. We learned a lot of things related to computer science. Many of these things are related to human science, and should belong to the area of psychology or something alike. That is one side of the dish.
30 years ago comments were demanded. Today we say that comments are bad among other reasons because they become outdated and misleading. 30 years ago the mantra was to keep the comments maintained along with the code and keep it up to date. Easy to say, but people tend not to follow that advice. For a while you can push the mantra and you can try to force people to keep their comments up to date but that is as futile as forbidding sex for a teenager. It is like trying to command gravity to stop and walk home dry while the raindrops float above your head. Human works differently and you can not alter human mankind. What is the solution we seem learned in 30 years? Adapt practice to what human can and will do.
If comments get outdated and misleading then it is better not to have any. On the other hand we need something to compensate for the loss of the feature comments provided. What we aim now is readable code. And this is the other side of the scale. This is something that changed in the world. We have new programming languages and new tools. If you were required to create readable code in FORTRAN or COBOL so that there is no need for inline comments you would be in trouble. Thus there was the strong push to comment. Those days the comments compensated for the language shortage and the outcome average was better including the misleading comments than naked code.
Today we have Java, Scala, C#, Go, Swift, Ruby, Python. All modern languages (sorry for those I missed) that make it possible to express the behavior and implementation in a readable and concise format that does not need comments. We also use unit tests, something that was unknown 30 years ago, which is more a documentation of the implementation than test. We use code to document, and ever less documentation going from waterfall towards agile. I hope that this is a good direction for some time and I look curious to the future.
| Reference: | Why we do not use comments from our JCG partner Peter Verhas at the Java Deep blog. |
I totally disagree with you! Most applications get modified over their lifetimes. Regardless of the language a programmer new to the code needs to know the objectives of each part of the code in order to be effective. Even the same developer forgets some details over time. Obviously, I am not a code purist. But I have had to modify “code purist’s” code and it needed comments in order for me to do my job in a timely manner. Part of the job of modifying code is modifying the comments. Some languages are easier to read than others, but they… Read more »
Agree 100% with Steve.
I don’t prescribe to a fixed percentage methodology – comment what is useful.
But it saves a LOT of time when having to do maintenance in code to have a single (or two) line comment inside the code that just explains the coders intention.thought pattern/etc.
When coding new solutions and not maintaining/updating them it is easier to say “I’ll do documentation later”. But – your thought process at that specific time is what is important to document.
30 years ago, programmers were relatively cheap and hardware very expensive. Memory was at a premium. People could and did write “bad” code deliberately if it was more efficient of computing resources, namely processing power and memory. The extra maintenance cost was considered an acceptable trade-off. Comments mitigated the maintenance of difficult to read code – they were necessary. Only after computing hardware resources gained power did variable and method names get enough length to become meaningful. Only then was structured code valued over absolute efficiency. It had nothing to do with being “stupid” and not even much to do… Read more »
Sorry to disagree but the code I hate to maintain or rewrite is that written by the “code purist”. Comments are not only needed but mandatory. Try maintaining code that has little to no comments. Try reading the doc’s if they exist, and then make a change to code written more than a few weeks ago. What use to be a matter of reading the comments is now a matter of reading the code and unit tests and then stepping through the code in the debugger a few time only to find it was a simple change that was needed.… Read more »
I am in complete agreement that comments are typically unnecessary. All too often they simply restate the code in non-formal terms focusing on what and not why. Frequently, when the code is changed the comments do not. I tend to delete that type of comment (along with useless JavaDoc that says “sets the value of X” or “gets the value of X” — frequently the comment block is bigger than the code block and IMO gets in the way of reading and understanding the actual code). What I don’t necessarily agree with is the reasons/justifications you give for not commenting:… Read more »
If you lot would just _read_ the article, you would see he is referring to inline comments, e.g.
I++; // increment I
He specifically excludes interfaces/API from his ‘ban’.
Mostly I agree with the article; inline comments only when code is complex and obscure; and that tends to be an indicator that a design rethink may be necessary
@Spafon Hi. Don’t know if that was directed at me or not … I treat comments as more than an indicator, more like a bowling ball dropped on my foot … As far back as 1978, Kernighan and Plaugher advocated “Don’t comment bad code … rewrite it”. Robert Martin, in his book Clean Code, makes the observation: The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express… Read more »
I also disagree with the author. Firstly there is an important false assumption in this strategy! It *assumes that the code is correct* and well written. Most of the times you need to read old code it is because there is an error in the code and you do not recognize the code entirely. It is then crucial to be able to discern what was intended and if that corresponds to what was actually executed. Sencond. I try to write pseudo code in order to solve the problem/algorithm well before coding. This is much harder if you need to remove… Read more »