Stories
Slash Boxes
Comments

SoylentNews is people

posted by Fnord666 on Thursday April 23 2020, @02:41PM   Printer-friendly
from the code-is-code dept.

"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?


Original Submission

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 2) by JoeMerchant on Thursday April 23 2020, @09:40PM (1 child)

    by JoeMerchant (3937) on Thursday April 23 2020, @09:40PM (#986215)

    Since 2006, I have called my abstraction layer "Qt" - it's pretty good, but invariably there's one (or more) other libraries that need to be pulled in.

    Porting Qt around is relatively easy, the other libraries tend to be a PITA.

    Projects tend to be all over the map: a 3D radiotherapy treatment planning app, an EEG polygraph/analysis suite, a chromatograph app, various UAV tools and an autopilot, video surveillance tools, another 3D treatment planning app but with a very different focus, a godawful suite of applications to hold together an overly complicated multi-processor device, etc. Each gets their own architecture, the only thing I've found that is consistently useful is a property system that all aspects of the system can uniformly refer to for IPC, persistence, etc.

    --
    🌻🌻 [google.com]
    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2  
  • (Score: 3, Interesting) by martyb on Friday April 24 2020, @12:05AM

    by martyb (76) Subscriber Badge on Friday April 24 2020, @12:05AM (#986285) Journal
    Yeah, I can see how that could be a problem. I suspected as much when I wrote my comment, but in the off chance it might be helpful, I wanted to put it out there just in case. Who knows, maybe somebody else reading along might see something there they will find useful. Anyway, I appreciate the reply and clarification. Thanks and best of luck to you!
    --
    Wit is intellect, dancing.