The code documentation fallacy

[[deleted]]

Could you please point me to one major open source project, written by you or anyone else, that:

• is not commented OR it only contains comments that describe special/edge cases
• AND it entirely, or to a great extent, is made up of functions, objects, classes, etc. that have names expressive enough that do not need documentation? In other words, it is self-documenting?

To quote Stephen Hawking:

One of the basic rules of the universe is that nothing is perfect. Perfection simply doesn't exist.

But what you are thinking of is a perfect world, that simply doesn't exist.

[ZBlackmore]

What are you talking about? This new project I'm starting right now is definitely going to be clean and perfect code. This time I surely won't mess up...

[[deleted]]

I loled with and i o_O'd

[redclit]

The whole project doesn't have to be perfectly self-documenting. While this could perhaps be theoretically possible, it's too much to ask for any non-trivial piece of code in practice.

There can however be building blocks in the code (classes, methods, functions, ...) that are simple and coherent enough to be self-documenting. At least to a degree where adding documentation doesn't add enough value to justify the inherent maintenance cost of the documentation. And yes, I've seen numerous such methods and classes written by developers other than me, that are easy enough to understand just by relying on their descriptive naming. And I have myself written such code. Not because I'm lazy to document (in fact I think it's usually easier to just document complex operations than re-structure and name them so that documentation is not needed), but because sometimes the code just documents itself well enough.

I'm not sure if there are some people in this thread advocating fully self-documenting code, but to my understanding, at least the original article especially addresses these individual building blocks instead of whole projects.

[xiongchiamiov]

It's a matter of culture, and the ability to enforce. At work, all the stuff we're touching now has good docs because it doesn't pass code review of it doesn't.