It doesn't matter how eloquent your code is or how you turned a bunch of code into a one-liner. If you are the only one who can read the code, have someone else go find a manager or executive...because it's their problem now.
Spell. Out. Your. Code.
Make it readable. Add comments, abstract it out into functions that read like a sentence.
Because at the end of the day, humans have to maintain it. Machines interpret it. So as long as the logic is sound, make it easy and pleasant to read.
Top comments (10)
Yes, but readability is purely subjective. Different readers have different reading levels, some prefer poetry to prose, some have larger vocabularies etc.
Way too often, 'readability' is taken as making it understandable to the most junior developer. This is clearly a bad idea.
I wouldn't really say it's purely subjective. There are traits to well-readable texts that code shares with posts or newspaper articles.
Studying guides like Microsoft Writing Guidelines, Clean Code and The Pyramid Principle of Writing helped me to take a lot of the subjectivity away. Even though these concepts come from somewhat different domains, they sound similar on many points:
Yeah, agree. It is subjective. This is what makes it hard. Also, how do you convey context in the correct way so that when you look at the code later it still makes sense?
The Clean Code book is a good read on this topic.
It is subjective.
Therefor it's a good idea to spell out with your team what the expected base level of the audience is.
Depending on that, you can decide what patterns, libs, styles etc... can be used.
E.g. I expect our team to know/learn entry level functional programming concepts like functor and monoid. I accept that monad is too abstract for most, so only introduce it sparcely and have it documented clearly.
Not taking it for granted us greatly beneficial to avoid lenthy 'yes/no' pingpong games.
Yes, a thousand times yes. This is a good mindset. Code is there for humans. We read a lot more code than we write, so spend that extra time on making it readable. Your team and future self will thank you!
Less code != better if you lose readability.
This, my friend, earned you my following. Preach on!
Amen!
The best example I can recall of how to eloquently explain your code is to name your functions, classes, properties based on what they intend, not what they are.