Which is superior?

Comments or self-documenting code?

Some would have you believe that code should be so self-evident that comments would be superflous. I can see some merit in that ideal.

Others would ask you to comment everything to help make it clearer. Hmm. Sounds reasonable, too.

So which is better?

I found a study on code readability that weighed in. And the answer is… nuanced.

From our results we found that documentation is something that software developers heavily rely on and that the need for extensive documentation differs with working experience.

It then expands on that later on:

Based on the survey we see strong correlations between the software engineers experience and how they would like their code documented. A student might prefer more documentation in order to understand the code while an IT professional tends to lean more towards the less is more model.

My main take-away from this?

Both self-documenting code and comments are valuable, but often to different types of people.

If you’re working on a codebase that involves professional developers (and you almost certainly are), then self-documenting code is something to aim for.

But, if you’re working on a code base that beginners (juniors, interns, or even actual students) might be working on, then you should also document your code well.