Litmus Test For How Well-Structured Your Code Is

by Justin Skycak (@justinskycak) on

Want to get notified about new posts? Join the mailing list and follow on X/Twitter.

Jason has a great litmus test for how well-structured your code is: are your variable / function / class / directory names both clear and concise?

If not, there’s a good chance the underlying design needs refinement. A fuzzy name often reflects a fuzzy idea.

And even if the underlying design is conserved and it’s just the names you simplify, you’ll still be thanking yourself later.

Clear/concise names act as guardrails on the entropy of the system. They help keep the complexity from eating you alive.

What it feels to get eaten alive by complexity:

  • "Where the hell is the code that controls XYZ, I can't find it anywhere"
  • "I found it, now I gotta decipher it"
  • "I'm trying to keep 10 things in my head all at once"
  • "I need to refactor this but I'm scared to even touch it"
  • "It's such a rat's nest it's not even clear how to refactor it"
  • "Been working on this for hours and I haven't even written any code yet"
  • "Just gotta power through and find a way hack it, if it works it works"
  • "Yeah, that sucked, hope I never have to come back to this code, because now it's even more confusing"

That’s what you save yourself from when you name things clearly/concisely and get the initial design right.

Well-structured, self-documenting code is a gift that keeps on giving.

Poorly-structured, hard-to-read code is the debt that keeps on collecting interest faster than you can pay it off.


Want to get notified about new posts? Join the mailing list and follow on X/Twitter.