this post was submitted on 13 Nov 2023
14 points (88.9% liked)

JavaScript

2008 readers
25 users here now

founded 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
[–] towerful 15 points 1 year ago

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.