DEV Community

Jonathan Irvin
Jonathan Irvin

Posted on

Let's get one thing straight: Code is read by humans, interpreted by machines

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.

Discussion (11)

Collapse
jonrandy profile image
Jon Randy

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.

Collapse
tqbit profile image
tq-bit

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:

  • The Pyramid Principle employs argument contexts. Those feel a lot like function contexts or classes
  • 'Write like you speak', 'Get to the point fast' and 'Be Brief' from the MS guide feel a lot like 'Write Readable Code For People' and the 'Single Responsibility Principle (SRP)' from Clean Code
  • SRP also reminds me a lot of the already mentioned, isolated argument contexts.
Collapse
simeg profile image
Simon Egersand 🎈

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.

Collapse
xtofl profile image
xtofl

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.

Collapse
lukeshiru profile image
Luke Shiru

I've been ask in the past to turn a vanilla JS module that exported a few utils with perfectly working JSDocs into a TypeScript class to make it "more readable". The one asking was a "senior" dev with a strong "OOP background". Readability is definitely subjective πŸ˜…

Collapse
ben profile image
Ben Halpern

Bart praise

Collapse
ivis1 profile image
Ivan Isaac

Agree

Collapse
simeg profile image
Simon Egersand 🎈

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.

Collapse
jwhenry3 profile image
Justin Henry

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.

Collapse
taijidude profile image
taijidude

Amen!

Collapse
gjorgivarelov profile image
gjorgivarelov

This, my friend, earned you my following. Preach on!