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 DannyB on Thursday April 23 2020, @04:35PM (2 children)

    by DannyB (5839) Subscriber Badge on Thursday April 23 2020, @04:35PM (#986091) Journal

    I like documentation generated by Javadoc/etc type tools. As long as it is informative and a pleasure to read. Write documentation that way. If you're just pointing out boring mundane details trivially discerned from the code, then you're doing it wrong. You should explain not only what it does. Why would someone use this function or class? What problems does it NOT solve? The documentation generator will get the mundane details like the function signature, return type, etc.

    Class or module level documentation is important. It's not about a single function. Maybe not even a single class type. For example a package that can represent the AST of some language. It may have many classes that at runtime can form a graph of input syntax. While each class needs some documentation, there is also a need for the much bigger picture documentation with examples.

    --
    People today are educated enough to repeat what they are taught but not to question what they are taught.
    Starting Score:    1  point
    Karma-Bonus Modifier   +1  

    Total Score:   2  
  • (Score: 3, Insightful) by maxwell demon on Thursday April 23 2020, @05:02PM (1 child)

    by maxwell demon (1608) on Thursday April 23 2020, @05:02PM (#986107) Journal

    The problem is that those tools create reference documentation. That is a necessary part of documentation, but it is not all documentation you need.

    Reference documentation is there for people who are already familiar with your code or interface, but need to look up the details. But it is not sufficient documentation. You also need documentation that is aimed on those who currently know nothing about your code. And yes, that documentation will contain information that is in principle already in the reference documentation (because if done right, the reference documentation contains all information). But it is structured in a very different way.

    --
    The Tao of math: The numbers you can count are not the real numbers.
    • (Score: 2) by DannyB on Friday April 24 2020, @04:00PM

      by DannyB (5839) Subscriber Badge on Friday April 24 2020, @04:00PM (#986522) Journal

      Reference documentation is useful if you want to look at the overall structure of a lot of modules, packages, and classes without the detail of the source code.

      When this generated documentation contains lots of useful human written information then it can be fantastic. Everything is hyperlinked so you can open it in another browser tab to dive deeper.

      --
      People today are educated enough to repeat what they are taught but not to question what they are taught.