DAVES Coding – E for Explained
The word ‘comment’ has an image of a petty statement easily dismissed, as in: “side comment”, “off-hand comment”, “no comment”…. Commenting source code deserves much more respect and attention. Code needs to be explained if anyone is to debug or modify it efficiently. It is time to talk about the best ways of ‘explaining’ code and move past mere ‘commenting’.
Studies have shown that it is 20 times more expensive to debug problem code than it is to write it in the first place. Thus, source code’s long-term value is not only a function of what you have today, but how easy it is to fix and maintain in future times 20. Pity the maintenance programmer. The programmer who has to fix your code (maybe “Future You”) has a job 20 times more difficult than your job today.
The factor of 20 should be considered when deciding what to put in an explanation. Debate rages – some experts insist code tells you ‘how’ while comments tell you ‘why’*. Other experts advise you to comment only what the code cannot say *. The problem with these conventional approaches is they assume the code works, but if comments are productive, it is probably because TEH CODEZ DONT WERK.
Unfortunately, in the real world, we spend most of our time dealing with code that DONT WERK.
Any explanation of “how the code works” becomes a cruel joke, because IT DONT WERK.
Of course, there is some chance that your code works flawlessly, in which case no one will care about your comments – why would they? It may be of some interest as a great masterpiece of clean code, but more likely, users will run your code and assume it is perfect. No one will read your comments until there is a failure or need for renovation, because most professionals are busy fixing things.
Problems – Why Explanation is Discouraged
(1) Commenting takes time. Therefore, you definitely should not comment too much. Figuring out what you think needs a comment also takes time. Figuring out what other people think needs a comment takes even more time. Figuring out what should be in comments is a bottomless pit of time wasting.
Save time – stop typing usele
(2) Too many comments wastes valuable resources. For instance, I have built up a library of every line of code I have written in the last 30 years. There are a lot of comments, and with wasteful duplication, back-ups and abandoned code, it fits comfortably in less than a Gigabyte. At this writing, I can buy a Terabyte of storage for $100, so the cost of storing my life’s work is on the order of 10 cents. With fewer comments, I might have saved 5 cents.
(3) Too many comments in the source code can break up the flow of reading and be annoying. Even worse, comments can create a subtle version of the ‘Stroop Effect’. Try reading the following list as fast as you can, then name the colors in the list as fast as you can:
|. red .|
|. blue .|
|. red .|
|. blue .|
You should notice a surprising difficulty in performing these simple tasks. The root of the problem is not in reading, and it is not in recognizing colors (unless you are color blind, of course), it is the interlacing of two tasks.
Proposed Solutions – D’oh
(1) Learn to touch-type fast and well. There are courses, there are applications, there are websites, there is a need. It is now part of the professional programmers job (though some standards were set down when it wasn’t).
Commenting takes time, but not much, especially since fixing code is 20 times more expensive than writing it. The cost comes during the quick part, the benefit is in speeding up the painfully slow part.
As a programmer, you should know what “code profiling” is. By identifying what code is taking the most execution time and resources, and what is negligibly wasteful, the programmer makes the best use of their valuable time. Use the profiling concept on your own daily work – debugging is probably where you need every advantage you can find, while typing too much is probably negligible.
Slowing down a bit is productive if your are forced to get your thoughts straight. Hoping that there will be no need for anyone to read our comments, we nonetheless write with 2 readers in mind – the programmer (maybe you) who has to fix the mistakes, and the person (maybe you) who paid for the line of code. They both deserve some minimal explanation.
Conscious of the need to keep moving forward, waste no time thinking about which lines need comments and which do not. Don’t waste time thinking about ‘why’ or ‘how’ – just leave whatever clues you can about the thoughts in your head right now, and move on.
Not long ago, commenting did have a real cost. Not only were disk drives expensive, but many programs were typed by paid typists onto bulky punch cards. Standards and the familiar look of source code became established, copied and taught during this period. Unfortunately, these old habits die hard.
(3) Try again after generous physical separation:..
Of course this is easier, and the benefit of separation should need no further explanation, although the Stroop Effect has been studied extensively. Studies suggest it is a hard-wired condition of being human.
What to Explain
What should be commented and what should not? A typical answer is some variation of “comment only what a reader will find difficult to understand”. Well, I understand baseball, but I don’t understand cricket. It might be the opposite for you, but not only should we be able to get along, as friends we are both stronger for our differences. Difficulty is in the eye of the beholder.
There is a fool-proof answer to the problem – comment the lines where the bugs are! Obvious, simple, efficient, valuable. Wait a minute – if you know where the bugs are, maybe you should just fix them.
The only way to enusre the line with bugs have comments is to comment every line. While seemingly excessive at first, it is not if you treat this as a goal, not a necessity. Working software is the necessity, and dead-lines are usually looming, so explaining everything is not your top priority.
That brings us to the our actual solution – explain as much as you can, when you can, while getting the job done. Programming is not just about typing things. Thinking is a major part, and the quality of that thinking is critical to success. Slowing down a little, without drifting off into some other topic, is very helpful. Typing and reviewing your thoughts helps to enusre completeness and correctness.
No one really wants to read your comments – they want the code to work flawlessly so they don’t have to.
Think of the Crime Scene Investigator – they need to record everything possible, even if much of it proves to be irrelevant. They record everything at the scene because they will never get another chance to answer questions they will ask tomorrow. Even so, they have to establish some perimeter to their investigation because there is a criminal they need to find right now. The Crime Scene Investigator does not want to use their extensive notes – they want the real criminal to confess.
If someone is saying you are writing too many comments, we ask you to think – is the problem that you are WRITING too many comments, or is it that they are READING too many comments?
We believe in E=mc2 – Efficiency equals massively commented code. We aspire to comment 100% of our lines of code, because we have no idea what line will be part of a future problem. Picture the maintenance programmer, desperate for any clue to make a fix and make a deadline. Try to leave a clue to a question that only “Present You” can answer – what were you thinking?.
However, the goal is probably unatainable because we have to move forward. To get closer to the goal, some comments may be as short as a single ‘.’ (i.e., period = end that sentence and thought) or ‘”‘ (i.e., ditto = same as above). Short comments do contain information – they indicate that “I have thought about it and concluded that there is nothing much to say”, rather than “I have abandoned the reader in my haste”. Some comments can be copied or automatically included using a ‘code snippet’ tool. Some comments are missing because we just had to move on.
Many comments are there because we had to come back and fix something the next day, proving “I am not as smart as I thought I was yesterday, but today I have learned the following…”.
E=mc2 – Old, Correct, Misunderstood
Besides a shameless attempt to ride on Einstein’s coat-tails, E=mc2 is a helpful analogy when evaluating expert knowledge and standard “best practises”. As far as we know:
- Einstein was correct.
- Established Newtonian Physics is a very good approximation for low (cosmically speaking) speeds, easily good enough to navigate to the moon and back, but is incorrect in its unstated assumptions.
- A century on, Newtonian Physics is taught first, and almost exclusively, in schools around the world.
- Acknowledged popular experts may not be much help. You will probably have to decide for yourself what makes sense and what does not.
- Unfortunately, if you want a job, you will also have to be an expert at the incorrect stuff. You could also do what Einstein did and get a job in another field, doing your best work on your own time.
If you are explaining enough to truly impact future debugging time, then probably someone will tell you today to cut back. At your job interview, they may like the “more commenting” idea, but DAVES standards are way beyond what they are thinking. You can cut back a little, but making cuts takes more time (“I would have written a shorter letter, but I did not have the time.” Blaise Pascal).
You need to cut back a lot to see a net increase in lines of code per day, paying the real price in the future.
It may be much easier to align your code with industry standards – around 10% of lines or less. In other words, though we hate to say it, you should probably fit in and dumb it down. (Even better would be an automated dumbing down tool. It is fairly easy to remove all comments, but it would be nice to have something that leaves a few random comments, and backs up the full explanation where the haters won’t see it. We’re working on it.)
We think you are a good programmer simply because you seek out stuff like this page, and have read this far. The industry needs programmers like you, so keep your job, do your best work on your own time, and keep us all informed of your progress.
We hope we are wrong, but for at least a decade or two, we don’t think you will be able to convince your boss or co-workers to make radical changes. You might be able to make a few small in-roads, if you:
- Advocate for a style that does not discourage commenting.
- Advocate for tools that do not discourage commenting.
- Advocate for a style that avoids the Stroop Effect (i.e. single-line comments well away from code, even off the page).
- Advocate for small steps in the right direction, citing credible experts.
- Are confident that you have thought it through, because you have.
- Aren’t a jerk about it.
- Write great code that gets the job done on time and makes clients happy.