“My Code is Self-Documenting”

http://ericholscher.com/blog/2017/jan/27/code-is-self-documenting/

87 99 9 years ago

codr4life2• 9 years ago

I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to be updated with the code.

RangerScience4• 9 years ago

I'd say then that your comments [regarding intent] are overly specific.

If updating the code block results in code with a different intent... you're not updating it, you're replacing it, and should take out the original comment with the original code.

If I have a code block to maintain data synchronization with a a server - that's the intent; if the code is updated from long-polling to websockets, the intent hasn't changed.

gnaritas2• 9 years ago

If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.

codr4life2• 9 years ago

Like I said, I don't agree with that particular broken record; there is value in stating the intent of code in normal prose as documentation.

jhlgkhkhil• 9 years ago

So they quickly fall out of sync with the code and cause more problems than they solve..

Clearly written code already expresses what it does unambiguously. If your code doesn't do what it is supposed to do that is a bigger problem.

wellpast2• 9 years ago

Code comments document the why, not the how.

I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.

quicklyfrozen• 9 years ago

So where would you document the "why" then? This is often the question I find most difficult to answer when reviewing code (including my own) -- after all, I can ferret out the what from the code.

jstimpfle• 9 years ago

There's nothing wrong with what your parent said.

If we are speaking of API documentation (i.e. function or module documentation): The "why" can't be explained here. It's at the caller side.

There are more rare cases where it's reasonable to document the implementation of a function because there's a particularly tricky section of code -- and documenting the "why" makes more sense to me here.

wellpast2• 9 years ago

If you're able to ferret out the what from the code, then your code must be defect-free.

Otherwise we need to know via the comment (contract) what is the what, so that we can fix the bug (or even know that there is a bug).

justin_oaks• 9 years ago

The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments.

It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.

joekrill3• 9 years ago

I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.

wnevets• 9 years ago

Comments are no exception.

but they usually are.

sparky_z• 9 years ago

The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check.

In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.

tigershark2• 9 years ago

Unit tests fail when they are out of sync. Guess what? An out of sync comment will never fail.

schmichael• 9 years ago

This is a reason to check comments in code reviews not to avoid comments completely.

macintux2• 9 years ago

The danger of stale comments is, I feel, overblown.

First, other developers know that comments can grow stale, so they're unlikely to treat them as sacrosanct, although I admit to falling into that trap.

More importantly, most of the types of comments that Eric recommends can drift out of sync with the code and still be useful. Why is this code here? What happened previously that is no longer in the code? What tradeoffs have been chosen?

mpweiher• 9 years ago

The danger of stale comments is, I feel, overblown.

Yes, because they should be, and are, largely ignored. Of course, deleting them is better than ignoring and not having them in the first place is better than deleting.

js82• 9 years ago

As others have said..

Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

derefr3• 9 years ago

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage.

This is not true of comments.

If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

RangerScience4• 9 years ago

I feel like this translates to "lazy* developers are a problem" rather than "comments are a problems".

Snarkily, how lazy* do you have to be to not even delete comments you make stale?

* And not as in the virtues of programming lazy.

sqeaky6• 9 years ago

It seems to me this is more of a knowledge issue or even a code/discoverability issue.

The closer a piece of documentation is to the code the more likely it is to be updated. External manuals always become stale and comments in C headers are more likely to be stale than comments next to the implementation in C source files (or in any language that doesn't even have that distinction). Comments directly next to complex formulae or other technical BS are most likely to be correct.

Some learn that then suggest getting rid of all comments or putting comments throughout all the code, but if we look at it another can can infer that some of it is code structure problems. A 2k line class with 200+ line methods with comments at the beginning of each method is more likely to have stale comments that any number of tiny classes with 10 line methods. Then comments on a 10 line method are more likely to be read too, because they need to describe less. Ideally they just add the "why" to the "what" the method's name provides. If the whole method and all the comments fit on the same screen then the dev ignoring it must be truly lazy.

ng122• 9 years ago

If you update code without updating the comments and it gets past review you have bigger problems than them being misleading. Good comments are dependent on good developers.

sqeaky6• 9 years ago

Good results of any kind are dependent on good developers.

DrScump2• 9 years ago

  The code gets updated but the comments stay the same.

It's especially sad when such practices survive code review. Reviewers, that's a symptom you aren't really reviewing what's going on.

lojack• 9 years ago

I treat the comments in my code as notes... things future developers will need to know, TODO's, occasionally why I'm doing things a certain way, or other things that may be forgotten. I try to make the code as readable as possible so comments aren't needed. If you really want the documentation, look at the tests. My test descriptions describe what the code should be doing. The actual tests describe the API. Then there's actual documentation. This tends to cover more high level stuff. If the code provides an API others will be using then I'll provide documentation on how to consume it, otherwise my tests describe the API.

All of that being said, I'm not dogmatic about any of the above. I'd prefer my code to be self-documenting, but I understand it isn't always for any number of reasons.

kyberias8• 9 years ago

Usually the people who cannot write good code love to write comments because they somehow feel it makes the code better. But they cannot write good comments either. Then everything is horrible. Code is really complex and hard to understand and the comments just make it worse. They might be out of sync or just erroneous.

I'm witnessing this currently with the code base I'm maintaining.

Fomite2• 9 years ago

All people who write bad code write bad comments = / = All people who write good code write good comments/don't need them.

lisivka5• 9 years ago

Yeah, «why you need comments? just read the code» (c) Brainfuck developers.

kyberias8• 9 years ago

Well, the point is that people who write good, clean code don't need to comment their code extensively. They don't need to continuously explain why they did some horrible hack or some trivialities because their code is well structured and very easy to understand based on other good software development practices. They don't write the requirements of their functions as code comments, rather they write unit tests that document the requirements etc.

davrosthedalek2• 9 years ago

I often work with code bases developed in academic circles. I.e. written by non-c.s. students. Of course they are not experienced programmers, how can they be, it's often their first real software work. There is no professional code review, the code is sometimes beyond ugly, fragile. Bugs get fixed by the next generation... I just ignore all comments. Again, it's not their fault, it is a given just from the situation. But in this situation, it's much better to teach them to write readable code first. And not to trust any comment already in the code.

derefr3• 9 years ago

Explaining previous approaches that didn’t work; explaining trade offs in the current implementation; marking possible improvements (TODOs) in the code; anything else you’d like to communicate with someone reading or developing the code

To me, those are the functions of commit messages, not code comments.

Of course, a "proper" IDE (and I don't know of any) would give you the context of the commit messages "impinging upon" any given line/block. Maybe something like Light Table (whatever happened to that?) could be configured to do this.

Presenting an example usage of the function and example output

And that's what (formalized) docs are for. You can certainly generate those from docstring-style comments, if you like, but personally I feel like they get it the way of editing the code itself, and would be better kept in separate files.

(Consider: would you put the gettext translation table for a string, inline inside the source file that contains said string? The arguments are the same, I think.)

fooey• 9 years ago

if you're looking at commit messages to figure out a piece of code, you're probably having a very bad day

yxhuvud• 9 years ago

Eh, that depends totally on the development culture. I do it all the time. Getting the history over time for a specific region is extremely nice when a piece of code is to be understood.

For the emacs users: vc-region-history is the best part of emacs 25. I totally consider it nice enough to motivate people to compile 25 by yourself if your distro doesn't provide it yet.

derefr3• 9 years ago

I feel like the most consideration that is ever spent reading a particular line of code, happens during the code review for the PR that introduces that code. When you're doing a code review, you read new code at the same time that you read the commit messages. The commit messages should explain+justify the code they commit. Heck, half the reason you can break commits down into little semantic pieces with tools like `git add -p` is so you can explain/justify each piece separately.

Really, rather than what I said above, it might be better if ever line of code were just always put in context of the PR+code review that allowed it to enter the codebase. Instead of git-blame(1), github-blame(1).

DrScump2• 9 years ago

There's a difference between figuring out the how and fully understanding the why. Comments are for the latter.

emodendroket6• 9 years ago

To me, those are the functions of commit messages, not code comments.

Yeah, it's definitely much more helpful to have it buried below hundreds of merge commit messages.

urig• 9 years ago

Self documenting code is not about the "how", it's about the "what". Ex: A method name should be FilterOutOddNumbers(). Not MapModulo2Predicate().

Indeed not everything can be expressed in methods and variable names etc and so comments can be helpful occasionally. But the focus must be on clearly written code with comments as an exception, not a rule.

As for SDC being myopic, I beg to differ. Code (and contents) is for developers and machines. End users and API consumers should have documents (hence documentation) available to them for purposes of tutorials, user guides and references.

RangerScience4• 9 years ago

+1 exactly this.

Aside from "why", or explaining overly clever one-liners, the kind of comments I always find necessary are those providing before/after example of data during a transformation; and example strings w/ resulting capture groups for regular expressions.

Example: # "tag1,tag2,tag3:val" => tags: [tag1, tag2], metadata: [tag3:val] # fun one-liner goes here

kyberias8• 9 years ago

No. Those are test cases that you put in your unit tests. You don't put data examples as comments in your code.

RangerScience4• 9 years ago

No. Why make myself or another developer find an entirely separate file in order to comprehend a line (or three) of code? Why leave in a line of code that is all but incomprehensible without an example or explanation? Why provide a paragraph of explanation when a single line of example data will be more informative? Why further decouple the "documentation" from the code itself?

Yes, you want test cases, and that's where you also put all the weird edge case conditionals; but, it's not like you're going to copy the actual line(s) of code into the test case, so you'd either need to temporarily copy the code (or the data samples) to be adjacent, or open side-by-side editor panes, or what have... All of this is more complicated than an example.

But what about sample data that doesn't fit on one line? Then either your sample data is too complex, or this method is unsuited to your situation.

There are guidelines for maximally legible code. There are no rules. If you follow rules, someday, you will encounter a situation where the rules force you to produce sub-optimal work. "Simply" strive to write legible code, and you will succeed. Strive to follow rules, and you will succeed at following the rules; and maybe you'll succeed at writing legible code.

kyberias8• 9 years ago

I think the Uncle Bob quote is good: "Code comments are not the Schindler's List. They're not pure good."

If a line of code has a comment attached to it, the reader needs to understand both the code and the comment. The comment is written in natural language. There are multiple ways of understanding it. It must be written with great care so that people reading it don't misunderstand it. Otherwise it will likely just confuse people. How about putting that effort in writing the code line with clarity? The reader must read and understand it in any case.

Stick with the code, people!

macintux2• 9 years ago

I really don't get this attitude. Code cannot tell you what is not there, no matter how clearly you write it.

kyberias8• 9 years ago

This is not black and white. Code comments have their place of course. For example, in sic. situations where one really needs to explain _why_ a certain approach was taken. But usually the why explanation is not needed.

Also, code doesn't have to tell you _everything_. It doesn't have to tell you "what is not there".

Maybe we can both learn here if you elaborated what you think code cannot tell, yet it should?

nercury• 9 years ago

No, the reader must not need to read the function to understand how it works.

The idea would be that the function names are so good that one does not need to read the function contents, right?

But some things are complicated and may not be expressible with the function name alone.

That's why people write comments. To help readers understand the code.

Let's say I am implementing some algorithm. I may mention the performance characteristics in the comment. Or I may let the readers dig into the code to find out what they are. Seriously, please don't follow "no comments" rule dogmatically.

kyberias8• 9 years ago

No.

If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works!

If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.

edblarney2• 9 years ago

"The reader must read and understand it in any case."

Because in the cases wherein the code is abstract or dense, a little 'English' can go a long way.

Especially when making use of APIs that are weird and have weird behaviours.

AKA: "I'm breaking xyz convention here because API abc has the following odd, undocumented behaviour (i.e. returns nulls when it should not)"

Comments are not always good, but if there is any reasonable thoughtfulness to them, they will be 'mostly good'.

phkahler• 9 years ago

The worst claim I've ever heard is that Simulink models are self documenting because they are flow diagrams.

emeraldd• 9 years ago

This is an odd one for me, 90% of the time I wind up subconsciously ignoring comments that exist in code. It's almost as if I can't see them on the screen. I've been in at least one argument with a coworker where I realized I was ignoring the existence of the comment he was referencing a line above the code we were looking at. On the other side of that, I'm usually adding comments about what's going on all over the place. At least partly to codify what the heck I'm thinking at the time I'm writing it.

To distill that down, document a lot but don't rely on comments you find to be correct.

braveo2• 9 years ago

I read code the way you would a book, constructing this model in my head. Comments to me are a big flashing warning sign saying "this is so important, we added extra comments".

If the comments aren't really that important it will start hurting my ability to read and understand the code quickly.

likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason.

I'm of the opinion that at the end of the day people need to be able to read code, not use comments as a crutch. There are times when non-obvious things should be documented so developer B doesn't go down the same rabbithole you did, but in general the code should speak for itself.

document gives the context, the code gives the details. If you have both, there should be no real issues with understanding what's going on.

sqeaky6• 9 years ago

I agree that accurately reading code is important, but no amount of reading just code tell you why something was done.

For a contrived example, why does a specific function/class use an array instead of a dictionary/hash table? A comment explaining that the dictionary was 500x slower in tests could fix that.

I suspect that is exactly the kind of comments you would want someone to "sit up and read" but I didn't want to assume.

edblarney2• 9 years ago

"90% of the time I wind up subconsciously ignoring comments that exist in code."

That's ok - because they are there for reference purposes.

So you can ignore them most of the time.

When there's an issue, or you are reading unfamiliar code - you can reference them.

I leave notes in the code as to the oddities/undocumented nature of weird API dependencies, and of things that were tried in the past and failed.

So many times I've tried to compile some off-the-shelf thing and failed because I didn't read the release notes.

You just have to read the release notes :)

So when you're perusing an unfamiliar module, read the comments :)

I grasp that they can become stale, but on the whole, decent comments are better than none.

kyberias8• 9 years ago

From my experience there is a correlation between the amount of code comments and defects in the code. The more I see comments in the code base of a module, the more likely it doesn't have any (unit) tests and the more it has defects.

Yet this may just indicate that the code is complex and therefore required comments and contains bugs.

In any case, high comment density is a code smell.

lisivka5• 9 years ago

LOL. Comments are not a part of the code. Good comments adds to readability, bad commenting style (e.g. enterprise style comments for everything) affects readability. Comments cannot add bugs to code.

What you think about spaces?

kyberias8• 9 years ago

Good comments adds to readability

I agree. I was talking about the _amount_ of comments.

Extreme example:

  void foobar()
  {
    // iterate over the list
    foreach(var item in list)
    {
      // send it 
      sender.send(item);
    }
  }

I've seen a lot of comments like this. They don't add value. They distract. They must be removed.

They also tell that the author didn't have a clear understanding why code comments should be written, so we may not trust his/her judgement in other programming decisions. The code is suspect. It's a code smell.

Isamu• 9 years ago

Most of our very large and complex code base lack comments.

But just yesterday I came across a particularly good comment in an else block, that summarized the story of "how could we have gotten here", and it involved far-flung failures and not so obvious interactions. Very informative to have that right there.

davrosthedalek2• 9 years ago

I'd rather have uncommented code that is clear and easy to follow than commented code which is not. Alas, what I actually get is wrongly commented code that is not easy to follow.

Best of both worlds or something.

bitdeveloper• 9 years ago

If comments in code are worthless.. then why aren't we all using some language that has no comment system built in?

randomdata• 9 years ago

I find it interesting to come across another discussion about writing good code with no real examples of where code has been improved through the use of the practices being advocated.

How am I supposed to know if the comments have really helped the code, or if is that the code was just not written in a self-documenting way to begin with? Or, form the other perspective, how am I to know if the self-documenting code isn't as self-documenting as the original author likes to think? Perhaps even more importantly, how will I learn to take on that better style without examples to study?

In a world where we have a treasure-trove of great open source software, you would think the first step would be to point to exemplar examples to show exactly what can be gained by writing code in the prescribed manner. The "I do it this way and it is great. Believe me.", unfortunately, does not make for a good discussion.

diyseguy• 9 years ago

Ironically, his article does not allow commenting

zquestz• 9 years ago

This might be the best comment on the thread. Your trolling skills are excellent.

tigershark2• 9 years ago

In my experience the worst code that I have seen was the one with the most comments. If your code is self-explaining, if you have a full test coverage that documents what the code does and how it should be used then the comments are completely useless unless you are publishing a library or an external API. In my current job I am required to add this completely useless Java Doc / xml doc comments for an application on which only I am working on, that is far more clear than the rest of the codebase, with extensive test coverage and currently I have the same amount of LOC and comments. It's a total and utter waste of my time and it decreases the productivity so much trying to read the code in the middle of the comments that I had to find a visual studio and Idea extension to hide the comments to avoid getting distracted by all that awful noise. Needless to say that I completely disagree with the author of the article and I hope that people sooner rather than later will understand that the living documentation of the code is in the code itself and in the tests that, by definition, can't ever be out of sync like the comments.

grokys• 9 years ago

I find that if your comments consist solely of commented out code, then you both don't need to comment in English and you remove the need for an SCM.

/says so many people I've worked with.

emodendroket6• 9 years ago

In particular, it is nice if you bother to document assumptions/constraints related to the expected input and output of your code; why should I have to trace the whole thing to figure that out?

morbidhawk• 9 years ago

code comments document the why, not the how

While I do agree with this since thoroughly reading the code itself tells you the how I find comments that tell me what it does to be just as helpful as telling why it does it.

I used to fall into the self-documenting code camp back when I programmed in Objective-C and long descriptive names with named parameters made it read like English but as I've read more code in more languages I actually prefer shorter names supported with code comments that tell me clearly in English what the code does.

For instance earlier today I was reading some of the source code in fossil-scm in the check-in.c file. In it there was a function that was simply named `locate_unmanaged_files`. If there wasn't a detailed comment preceding that function I would have assumed it merely found the files and reported on them directly but after reading the comment explaining what it did I realized it stores the files in a temporary SQLite table, after reading that I learned that "locate" had a wider meaning then to just find it and return it but it rather meant that it is now located for any part of the system to find in the database. It would have taken careful reading of the code to have realized this and it helped me to better focus and understand the code I was reading.

ilaksh• 9 years ago

One thing not mentioned is that in an earlier era, code absolutely could not self-document at all. For instance, assembly language in the 80s. Many systems just did not allow for practical longer descriptive names.

Or the traditional C style with extremely long functions that do many things, cryptic names, hardware-related constants or magic numbers, little to no facility for modularization or composability etc.

In that era it was an absolute truism that comments were important. In today's era, comments are usually a symptom.

vinchuco• 9 years ago

As someone who had never heard the "self-documenting code" term, I imagined a machine-learning-assisted 'autocomplete' of sorts for code comments or a genius.com for code.

“My Code is Self-Documenting”

Related Stories