Self documenting code is more about using sensible names and explicit code.
So addItemToCartByProductId
instead of updateCart
.
The idea being, once you get the hang of an API, you can pretty much just guess what the name of the thing you want.
And this applies at all levels.
So cart[id]
might be better as cart[productId]
because id
is ambiguous. Is it the id of the cart? Is that keyed by some user session?
Suddenly you are having to maintain a larger scope in your mental model to try and understand what's going on.
You could argue the cart variable could be named better. Or perhaps it's an internal variable, and it gets wrapped in accessor/mutator methods or whatever.
It's the names and syntax that should tell you what things do.
Comments should tell you why complex or obtuse things are being done.
However, code used by multiple people (eg libraries, APIs, open source projects, group/company projects) absolutely need the meta-docunentation. The JSDocs, the readmes, examples, install, config, API overview and all that.
Wikipedia has a good entry on it.
https://en.m.wikipedia.org/wiki/Self-documenting_code
Notably the "objectives" part:
Reduce the need for users and developers of a system to consult secondary documentation sources such as code comments or software manuals[2]
Reduce, not remove.
So the documentation still needs to exist.