Self-documenting Code

Aijan@programming.dev to Programming@programming.dev – 84 points –
Self-documenting Code
lackofimagination.org
72

You are viewing a single comment

Ew no.

Abusing language features like this (boolean expression short circuit) just makes it harder for other people to come and maintain your code.

The function does have opportunity for improvement by checking one thing at a time. This flattens the ifs and changes them into proper sentry clauses. It also opens the door to encapsulating their logic and refactoring this function into a proper validator that can return all the reasons a user is invalid.

Good code is not "elegant" code. It's code that is simple and unsurprising and can be easily understood by a hungover fresh graduate new hire.

Agreed. OP was doing well until they replaced the if statements with ‚function call || throw error’. That’s still an if statement, but obfuscated.

Don't mind the || but I do agree if you're validating an input you'd best find all issues at once instead of "first rule wins".

Short circuiting conditions is important. Mainly for things such as:

if(Object != Null && Object.HasThing) ...

Without short circuit evaluation you end up with a null pointer exception.

I agree, this is an anti-pattern for me.

Having explicit throw keywords is much more readable compared to hiding flow-control into helper functions.

This is the most important thing I've learned since the start of my career. All those "clever" tricks literally just serve to make the author feel clever at the expense of clarity and long-term manintainability.

I mean, boolean short circuit is a super idiomatic pattern in Javascript

I think that’s very team/project dependent. I’ve seen it done before indeed, but I’ve never been on a team where it was considered idiomatic.

Because on JS the goal is to shave bytes to save money on data transfer rates

It's not that deep. It looks nice, and is easy to understand.

Good code is not “elegant” code. It’s code that is simple and unsurprising and can be easily understood by a hungover fresh graduate new hire.

I wouldnt go that far, both elegance are simplicity are important. Sure using obvious and well known language feaures is a plus, but give me three lines that solve the problem as a graph search over 200 lines of object oriented boilerplate any day. Like most things it's a trade-off, going too far in either direction is bad.

assert(isPasswordGood(...)) is already in the language. node