SoylentNews is people
SoylentNews
"Good Code Documents Itself" and Other Hilarious Jokes You Shouldn't Tell Yourself:
I didn't notice this story when it appeared on Hackaday just over a year ago. I'm well aware this has all the hallmarks of devolving into an emacs vs vi battle. Yet, the story does raise some interesting points about the different kinds of comments. That some comments are worse than useless and others can have great value. Without further ado, here's the introduction:
Code documentation — is there anything more exciting than spending your time writing extensive comments? If I had to guess, your answer is probably somewhere along the lines of "uhm, yes, everything is more exciting than that". Plus, requesting to document your code is almost like an insult to your well thought out design, this beautiful creation you implemented so carefully that it just has to be obvious what is happening. Writing about it is just redundant, the code is all you need.
As a result, no matter if it's some open source side project or professional software development, code documentation usually comes in two flavors: absent and useless. The dislike for documenting ones code seems universal among programmers of any field or language, no matter where in the world they are. And it's understandable, after all, you're in it for the coding, implementing all the fun stuff. If you wanted to tell stories, you would have chosen a different path in life.
This reluctance has even formed whole new paradigms and philosophies claiming how comments are actually harmful, and anyone trying to weasel their way out of it can now happily rehash all those claims. But, to exaggerate a bit, we're essentially villainizing information this way. While it is true that comments can be counterproductive, it's more the fundamental attitude towards them that causes the harm here.
In the end, code documentation is a lot like error handling, we are told early on how it's important and necessary, but we fail to understand why and instead grow to resent doing it again for that same old teacher, supervisor, or annoying teammate. But just like error handling, we are the ones who can actually benefit the most from it — if done right. But in order to do it right, we need to face some harsh truths and start admitting that there is no such thing as self-documenting code, and maybe we simply don't understand what we're actually doing if we can't manage to write a few words about it.
So let's burst some bubbles!
I found the rest of the story well worth the read. Highly recommended! I'll be the first to admit that the coding example has shortcomings. But it did serve as a concrete basis on which to launch the discussion.
In my experience, all too often I find myself updating code I'd written a year ago. Or 10 or 20 years ago. I've come to see the value of some of my comments. Especially those that remind me of what I was intending to accomplish in a certain code sequence and how I was accomplishing that goal. Some of my code is self-documenting. In other cases, I was so far into the weeds just trying to get it to work, that I just knew that a year or so later I'd not recall the details and would be furiously scratching my head trying to remember what I was doing and thinking. And in still other cases, I found comments that, although accurate, failed to be of any help!
By writing comments to my future, defuddled self, I try to explain things to make the next update easier. If it's all I can do at that moment to write the code and get it working, what hope do I have of ever coming back and trying to debug (or extend) it when it's no longer fresh in my mind?
When reading through others' code, I am grateful to find comments which provide assertions of what the goal was and other comments explaining how that goal is being achieved. I can then look at the code, see how it supports that effort.
Anecdata: I had a professor in college who could not go down to the computer center (back in the days of mainframes and punch cards). Any appearance there and he'd be besieged by students with questions! So, he would give a handwritten copy of the program to a grad student who would go to the computer center to enter, run, and debug it for him. Almost without exception, the grad student would report that if the computer could run his *comments*, the code would basically run the first time! That such a learned and experienced programmer that I held in very high esteem would make such a plain-spoken admission of his poor coding skills and of the value of writing comments made a long-lasting impression on me!
So, fellow Soylentils, what has been your experience with code comments? What kinds of comments have been most helpful to you? As an example, think of reading a function which returned a T/F flag as to whether or not the year passed in as an argument was a leap year. Imagine debugging it, with and without comments. If it had no comments, what comments would you wish it had? How does the programming language affect your approach to comments?
(Score: 2) by meustrus on Friday April 24 2020, @06:19PM
I think Java (and Java/OO dogma) is the root of a lot of code comment hatred these days. Even worse, I think that hatred has made it significantly harder to maintain documentation in any system.
So many people used to say that code comments are good. That documentation comments are better. That every single function should be documented.
In the OO world, this expanded to describing classes too. The problem with documenting classes is that you don't know why you want that class in the first place.
But that's not the worst part. Java/OO dogma says that public fields are bad. That long method chains are bad. That everything needs to be completely "encapsulated", so every object that controls something useful has to proxy every single access for every "encapsulated" object.
So we end up with a bunch of useless proxy functions, because dogma. Everyone knows they're useless. Nobody understands the OO concepts well enough to provide real encapsulation, and even if they did, Java dogma asserts that not only should everything be an object, but those objects should do everything. It's nearly impossible to write code that conforms to Java/OO dogma and style while satisfying the UNIX philosophy to do one thing, do it well, and do it in a way that encourages flexible re-use.
Being stuck in a situation where 80% of our code is garbage proxy functions we can't get rid of, what do we have to do next? Give the garbage proxy functions documentation comments.
So every POJO with X number of fields needs 2*X number of functions, each of which needs a meaningless documentation comment including all manner of extraneous metadata that nobody actually cares about. The functions really are self-documenting; when you getThing(), it returns whatever was passed to setThing(...). That doesn't matter to the documentation comment dogma.
Keep at this a few years and everyone is sick of seeing all the garbage documentation comments for their garbage proxy functions. Garbage in garbage out, as they say. So our tools adapted. Now you can automatically hide all of those garbage comments!
But how does the tool know which comments are garbage? It doesn't! It just hides all comments, all the time!
People say comments are always out of date. That doesn't happen by accident. It happens because we ignore the comments. It happens because our tools tell us to ignore the comments. It happens because 80% of those comments were garbage to begin with, because 80% of those functions are garbage to begin with.
Maybe comments would be great again if we went back to the days when they were they only thing keeping the cosmic horror at bay. When you had no hope of figuring out on your own how the computer knows how to "get_temperature", so for your own sanity and everyone else's you had better explain that. When out of date comments hurt people so much they had to go back and fix them when they learned the truth.
Then again, I'm happy that most of the time I don't need to rely on comments to explain things. I can just read the code.
The best documentation is pretty hard to put next to the code anyway, because it explains how to use the system as a whole. So the best documentation really is going to be automatically-verified example code showing correct implementation and usage.
Which is not to say there won't be times when the "what" or the "how" are clear enough, but the "why" is not. I like to think that when code comments are rare, though, the ones that exist catch the attention better.
At least, when the IDE isn't hiding them by default under the assumption that it's a garbage documentation comment written for one of dozens of garbage functions in an Object with too many responsibilities.
If there isn't at least one reference or primary source, it's not +1 Informative. Maybe the underused +1 Interesting?