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: 5, Insightful) by JoeMerchant on Thursday April 23 2020, @06:22PM (7 children)
As the years roll on, I use private and protected less and less.
I'm not writing APIs for other boneheaded programmers to use, I'm writing code that will be shared among a small team of professionals. When I say: "use the getters and setters, unless you know EXACTLY what you are doing" I mean that, and they usually figure out why it's important fairly quickly.
The number of times I've declared something private or protected and had to go back and change it is infinitely larger than the number of times I've declared something public and later regretted it.
🌻🌻 [google.com]
(Score: 3, Informative) by Anonymous Coward on Thursday April 23 2020, @06:45PM
There's no point to private/protected, except as a hack to enable faux-encapsulation using the c struct model. No matter, the compiler and the cache see all!
If you want real encapsulation, use a pimpl.
If you want perfect, future proofed encapsulation, use a function defined in another translation unit.
Two generations of programmers have been taught to make code more complicated instead of less.
(Score: 2) by HiThere on Friday April 24 2020, @01:28AM (3 children)
To me the private and public declarations are important. When *I* use the code later, I want to be reminded about how I intended that variable to be used. I've never worked on a project where other people did part of the coding or design. And *I* consider public, private, and protected to be useful declarations. I don't have any problem with this being a convention ala Python and leading underscores. But I want it reflected in the detailed documentation, and I don't want to need to write a note on each variable about how it should be used.
I suppose that if the language didn't support encapsulation .... no, that's wrong. One of the reasons I dropped C was that it didn't support encapsulation. Even Fortran IV was better, with named and numbered common blocks. (Admittedly, I switched to Mortran long before I used C++, but that was over structured programming availability. Mortran was a preprocessor that spit out Fortran as the result which fed into the Fortran compiler. Vala did something similar with C a year or so ago, and for all I know still does, but it's intermediate code is a lot less intelligible.)
These days I generally program in Python, so my documentation is with Doxygen (Sphinx being useless for my purpose). I really like D, but the lack of available libraries is really a killer. And for some reason WxWidgets works better from Python than from C++. If I get around to writing end user documentation it will probably be in LibreOffice. It doesn't do a good job in indexing, but it can do a basic index and it produces a decent table of contents. (FWIW, the best indexing word processor I've encountered was MSWord 5.1a for the MacIntosh prior to system 7. It's major defect was that it could only produce one index, so you couldn't have separate index for alphabetic and chronological entries. But they were sorted, so you could sort of fake it.)
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 2) by JoeMerchant on Friday April 24 2020, @02:38AM (2 children)
I've tried to like Python a couple of times. I pick up a project and say "I'll do this one in Python, it'll be fine..." I get through a bunch of it and it's fine, performance is running around 95% of C++ performance. Then I hit something that needs to iterate a lot of tight loops and Python basically freezes in its tracks, 0.01% of C++ performance. And, sure, that's not what Python is for, use a specialized library in C or something to do that and then call it from Python, the Python die-hards will say.
Wait, what?!???
So, you code in this language because it's "easy," but in exchange you have to wrangle an unruly collection of "helper" modules (which constantly teeter on the edge of dependency hell) that do the actual heavy lifting in other languages, and if you can't find a ready made module that does what you want, you get to make your own. I spend a few hours casting around looking for something that will do what I want, it doesn't exist, then I spend a couple of hours trying to figure out how to code my own Python callable module, then I figure: "I could have had this whole thing done in C++ about 3 hours ago...."
I think I've run that cycle 3 times in the last 12 years now... and still Python continues to gain popularity...
🌻🌻 [google.com]
(Score: 2) by HiThere on Friday April 24 2020, @03:13PM (1 child)
It definitely depends on what you're doing. I don't usually use lots of tightly nested loops these days. (I sure did back when I was doing transportation modeling, though.)
What I really wish was that they'd get the bugs out of Vala, and remove its dependencies on gnome (which I feel has gone off the deep end and can't swim). (I think the dependencies are really on gtk, which isn't too bad, so maybe it was the packaging. The bug were bad enough that I didn't look carefully. Of course, this was a couple or three years ago when I last looked at it carefully.)
Javascript is what you use to allow unknown third parties to run software you have no idea about on your computer.
(Score: 2) by JoeMerchant on Friday April 24 2020, @05:47PM
My latest frustration is "machine learning" which everybody swears Python is ideal for, but if you want to make synthetic (or partly synthetic) data to train your models on, as far as I can see Python is useless... but it may be easier (in the end) to run a hybrid Python / C++ with C++ doing the data synthesis. I'm still trying to use the C++ ML libraries and do it all in C++, but the C++ interfaces seem to be falling into obscurity quickly - even though Python is mostly just a wrapper on them.
🌻🌻 [google.com]
(Score: 0) by Anonymous Coward on Friday April 24 2020, @02:17AM (1 child)
is your friend :)
(Score: 0) by Anonymous Coward on Friday April 24 2020, @02:21AM
const_cast is your friend :)