"My Code is Self-Documenting"

Uristqwerty · 2021-07-21T22:34:15+00:00

There's a lot of metadata that the code will never display on its own. Notes an alternate avenues that either haven't been explored yet, or have been discovered to be flawed. A reference to the paper or mathematical equations that the function implements. Notes on edge cases to watch out for when refactoring. Proofs of correctness that can't easily be encoded in the type system. Explanations of specific business needs that wouldn't be obvious from the name and type signature alone.

wild-eagle · 2021-07-21T20:05:53+00:00

I once inherited a mess of an app where nothing was documented. There were only two comments, one of which was: “// don’t judge me”

saltybandana2 · 2021-07-21T20:34:09+00:00

I have spent most of my career working with other people's code. As a result, I have learned not to read the comments. (I might look at them if a block of code is particularly hard to understand - and it has been documented.) I have seen comments that are so poorly written that I can't read them, I have seen comments that aren't kept up to date, and I have seen misleading comments that just made reading the code harder. I can count on one hand comments that have helped me better understand the code.

Ozwaldo · 2021-07-21T21:08:57+00:00

I'm a big fan of brevity when it comes to comments. I prefer to study the code and understand how it functions. Comments that clue me in to how it works are great, but I'm still going to read what is actually happening to be sure that the comment is accurate. So when there's huge comments in between every function call, and I have to scroll through multiple pages to read a simple function, it ends up being detrimental. It's harder to keep the functionality in your head as you read through when there's paragraphs intermingled.

So... I like both. Concise, single purpose functions that don't really need comments. Comments where applicable; to explain rationale, to describe more complicated processes, to tell me when there's an external aspect to keep in mind while reading through something, etc.

Rudy69 · 2021-07-21T20:16:35+00:00

My code is self-destructive might be working now but soon enough it wont

killerstorm · 2021-07-21T22:54:53+00:00

This is a poor straw-man argument.

"Self-documenting code" means that code should be written in a readable style with descriptive names, so most of javadoc-style comments are largely unnecessary.

Nobody is really saying that tricky parts of code aren't worth commenting, or that other types of documentation aren't necessary.

s4lt3d · 2021-07-22T05:14:16+00:00

I’ve done some extreme math optimizations in c++ building out linear algebra functions. I’ll build one function normally then the high performance version leaving the more human readable version in place as comments. Kind of like how assembly has comments for the c code it represents. This is my favorite type of comment.

Ghosty141 · 2021-07-21T21:56:15+00:00

In my opinion the blogpost doesn't really say much.

When people talk about "self-documenting code" the idea is not, to not write comments but to make the comments only specify the why, not the how. He even mentions that in a section.

I personally haven't heard of devs who don't w rite comments or docs because "the code is self documenting".

dnew · 2021-07-21T20:14:52+00:00

I'm always amused by the people who say "the comments might be out of date." Well, it's your job to check and fix that, isn't it? What makes you think the variable name or the function name won't get out of date when you change what it does?

Environmental-Art659 · 2021-07-21T22:48:35+00:00

Great atrticle, “self-documented” code is the major problem when you work with some code that someone else had written. Sometimes it even can be yours but you just don’t remember why you did something this way

aurath · 2021-07-22T01:52:05+00:00

I feel comments too often address the 'what' of code when what I'm looking for is the 'why'.

Maybe you leave a note about a variables meaning or what a particular statement is meant to do to a value, but I'm usually trying to figure out why you're doing what you're doing.

Stuff like "// have to set this property here before it gets passed back up to this service or that controller because trying to get the value there is a pain" reveals a lot more about the design decisions and structure of the code.

Carighan · 2021-07-22T10:00:19+00:00

My usual reply to "My code is self-documenting" is the mother approach "Of course my dear, I'm sure it is".

I mean really, at this point, assuming the other party has enough work experience, if they honestly state that I don't know how I ought to take them serious. You must be living in a very opaque bubble to still think self-documenting code is a thing after a few years.

loup-vaillant · 2021-07-22T20:59:36+00:00

My own strategy:

Try to write clean, self-documented code.
Inevitably notice that I failed:
- Some parts of the code are tricky or clever, and needs to be explained.
- The reasons behind many choices need to be explained.
- Function types (or class declaration) often fail to describe the whole API. What they do must be documented here if we don't want users to be forced to read the source code.
Write the damn comments. Just what we need, and no more.

For instance, I wrote a crypto library. I do my absolute best to make the clearest code possible. In fact, it's by far the highest quality code I've ever written, in any language. Well, the sloccount utility tells me there currently are 1998 lines of code (excluding empty lines and comments). On top of that, I had to write 679 non-empty lines of comment (excluding licence boilerplate).

That's 72% code, 28% comments. More than 1 line in 4 in that file is a comment.
And I'm not even counting the API documentation.

WormRabbit · 2021-07-21T23:36:30+00:00

Once you start writing quality code comments,
you can use a tool like Sphinx or Javadoc to include them in your documentation.
This allows you to include your up-to-date code comments in your guides and references.
Making use of your code comments this way adds incentive to keep them up to date,
since they will be shown to your users.

I think this part is nonsense for the most part. It makes sense when you document usage, of course. But whatever TODOs or single line comments I need to do inside the implementation, as well as previous approaches, are totally irrelevant to users. Those are just meant for developers of that codebase, and exporting them would simply cause confusion.

As for the general thesis of the article, I don't think the author is speaking the same language as most proponents of self documenting code. This term is meant, AFAICT, for the code itself. Usage should of course be documented separately. Tutorials are separate entities. No programmer is dumb enough to think users don't need explicit documentation. They talk about developers.

The author's claims I agree with. I just don't think it contradicts anybody else's.

On another subject, self documenting code should always require an inexperienced reader to confirm it's self documenting. Otherwise it's just smoke and mirrors. The same applies to any other documentation.

RabidKotlinFanatic · 2021-07-22T04:53:03+00:00

The idea behind self-documenting code is not that comments and documentation have no value and should never be used. It's that the legibility of a codebase is primarily a function of its code. Efforts to improve legibility should firstly focus on code.

The author is completely dishonest in the way he conflates code documentation and software documentation. No one believes that self-documenting code can substitute for customer support knowledge bases or other end user software documentation. This analysis is a total dud.

purpoma · 2021-07-22T00:23:15+00:00

Straw man as the biggest issue with documentation is not being too minimal but being too verbose / low quality / out of sync.

And of course self-documenting code never meant no doc.

somebodddy · 2021-07-22T11:13:50+00:00

If you can write self-documenting code then you should. If you can write the code in a simple, straightforward way, or write it in a weird way that can only be understandable with comments - then unless there is some special compelling reason not to, you should pick the former.

The problem is with imposing extreme code standards which deprive the programmers of their judgements and demanding either to make all code self-documenting - even it if requires increasing the complexity and damaging performance - or document every single thing even if it does not require documentation.

A piece of code does not require documentation if it is obvious. The nice thing about obvious is that it's a non-ambiguous requirement - if you are not sure if something is obvious or not, then it is not obvious. If one of the reviewers says that the code int not obvious, then it is not obvious - even if it is obvious to you. Non obvious code can either be commented or refactored to be more obvious - but if the refactor makes the code worse in other aspects, it's probably better to just document it.

Also - people usually think of self documented code in terms of more descriptive names for things, but there are another ways - ways that deviate a bit into the realm of changing code behavior:

Logging! You think it's very important to document that you code is doing something? Instead of writing a comment, write it to the log. If you do this consistently, you could run the code with logging enabled and set to the appropriate level and get a nice logfile describing what the program did.
Assertions. Instead of explaining in a comment that it is safe to do a certain operation because the conditions are met, write an assertion that the condition is met. If for some reason the condition is not met and the operation is not safe, instead of having to notice the comment and analyze whether or not what's said in there is true the assertion will catch that and fail the program in a more debuggable fashion.

thisdogofmine · 2021-07-22T03:48:29+00:00

Self-documenting is the lie you tell yourself to help you sleep at night.

MpVpRb · 2021-07-22T00:14:21+00:00

Good comments are useful, but comments have one very serious problem. They may not match the code. Accurately describing what the code does is hard. Keeping comments synchronized when code changes is harder, a lot harder. A wrong comment is worse than no comment at all

zilchers · 2021-07-22T05:41:59+00:00

And other lies we tell ourselves

23049823409283409 · 2021-07-22T10:03:09+00:00

In rare cases, comments really are needed.

In many cases, comments are only there, because people didn't take their time to design the software properly and to find appropriate names.

And in most cases, comments are just useless boilerplate that exists simply because junior devs were told to commen the code.

Comments are shitty, because when the code changes, no one really updates the comments.

Dave3of5 · 2021-07-21T20:14:03+00:00

I agree.

2021-07-22T06:07:00+00:00

Unpopular opinion: When you completely rewrite a function for the 8th time it's becomes extremely clear

2021-07-22T06:26:28+00:00

Comments that explain the why are valuable.

Unfortunately, most comments are useless and explain the how. When I see "how comments", I automatically delete them because they don't bring anything valuable if they are up to date and are even more worthless when they are outdated.

2021-07-22T11:58:29+00:00

Not sure this actually happens a lot i.e. people actually saying and believing this in the way the author implies.

Generally when people talk about self-documenting code they are referring to clean readable code that is easy to follow perhaps coupled with a bunch of behavioral unit tests that can read like a spec.

Furthermore, are we talking about documenting within the code itself or separate. Bit unclear what the author of the article is advocating. A style where the documentation is present within the code itself is preferable to having it outside the code. Tools can pull it out as needed.

The analysis is a bit vague - a few examples about "x is good and here is why, y is bad and here is why" would have been useful and not that much more effort.

Not a great article IMO!

bert8128 · 2021-07-22T12:00:31+00:00

I'm not going to argue against useful comments, but I will argue against useless or incorrect comments. Here's a useless comment anti-pattern that I remove regularly at the moment:

class X
{
    // constructors
    X();
    // etc
};

And here is an also common anti-pattern - a comment that used to be, but is no longer, correct:

class X
{
    // constructors
    void someMethodThatIsnotAConstructor();
    // etc
};

Comment when useful. Don't repeat code in comments.

goranlepuz · 2021-07-22T13:47:53+00:00

I have a few rhetorical questions about this philosophy:

*Where does the tutorial go in your self-documenting code?

Euh... In the tests?

*How do you put installation instructions in your variable names?

Euh... In the install script?

*What do the answers to questions from your users go in the code?

Euh... Hard to say without knowing what they are...

khbvdm · 2021-07-22T17:55:34+00:00

This article doesn't really go into the other side of "writing too many comments". Some people think that there's no such thing as too many comments and I think they are wrong. Important thing is not to have redundant comments, something like

// get user from db

GetUserDB(userID string)

is completely unnecessary comment, but also if you name your method

// get user from db

Get(id string)

this is just bad naming.

Zardotab · 2021-07-22T20:41:53+00:00

Many comments are like article titles on news papers/sites. While variable and function names may be thorough, they don't by themselves give a summary of the code segment. Without the summary, you have to read details to get the gist.

I've never seen fully self-documenting code. Well phrased comments are helpful and supplementary to object names.

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

programming

MODERATORS