A lot of people talk compare good code to poetry. Poetry is generally:
- Elegant and enjoyable to read.
- Of variable information density. Sometimes, a line of poetry can contain multiple meanings. Sometimes, it’s more verbose.
- Subjective and potentially ambiguous. Different people reading the same poem might interpret it differently.
But often, good code should be more like an essay:
- Of the right information density. It exposes important information and hides unimportant details. Not too verbose, not too dense.
- Well-structured and layered. Different layers will expose different levels of detail.
- As clear and objective as possible. There is one clear interpretation of what’s happening.
- As simple as possible, but not simpler.
- Often written and re-written.
If you’re writing hobby code that only you will read and not maintain, write code like poetry. Make magical, whimsical, and fun. Make it clever. Write what flows out of you.
If you’re writing code that others will read and maintain (and as a hint, “future you” is generally an other), write code like an essay. Don’t make it clever or artistic. Make it simple, clear, and easy to read and understand.
It will be read far more often than it was written, and the person reading it probably won’t be looking to enjoy your “art”. They’ll just want to know what the hell is going on so they can get on with their day.