There’s just so much wrong in there.

Code is a programmer (or the programmer part of a developer) dumping their thoughts into a machine-readable format, and ideally, only the machines executing it will ever need to read it, while other humans only need to interact with the documentation you leave them.

Making code easily readable to other people is a secondary goal that often does not go together with requirements of correctness, efficiency, and timeliness once you get past trivial boilerplate. Sure, if you’re talking about the N+1st implementation of a “baby’s first blog” web application, it’s entirely possible to keep things readable. That’s what the write-up is concerned with: the web, a swamp of bad practices, quick&dirty one-shot solutions, and people who think that their approach to do something will be a fit-for-all. Rails is a big offender in the last category with all its opaque magic built on top of a very permissive language, subtly breaking things and making diagnostics nigh impossible once you get past the few trivial cases that were respected in the system’s development. The loose and forgetful development of PHP has brought us two decades of vulnerabilities through negligence, and only now that massive amounts of money and actual skill are being sunk into the language and surrounding ecosystem, things start to look up.

If you, say, start interacting with “creative” business logic that needs to handle intricacies of dozens of different service providers, decades of hacked-together “standards”, and nontrivial amounts of money on the line—which is my world at the moment—, your “human readable code” becomes a matter for actual documentation of the whys and hows. Why are you splitting operations weirdly when theoretically a certain API call could do it all at once? Why do you special-case something based on a weird combination of details in an order? How did you determine what to do? What should a maintainer look out for later on? Will something need to be revisited at a certain time?

If you need to put huge amounts of data through mathematical transformations efficiently (think high-performance computing or even “easy” tasks like making a game look pretty), you start dealing with low-level details of your platform and mathematical concepts that just will not be readable once they’re transformed to the limited set of expressions your compilers and other tools can understand. It’s once again time to split things up between talking to a computer and talking to people. Reference articles describing the weird and wonderful algorithms you’re using, make sure the next one to touch your code won’t break a necessary but fragile optimisation, etc.

In the end, sure, you can get small things done with the advocated drive-by approach to the craft, but you will cause problems for everyone who needs to deal with your results down the line.

Like what you read? Give Nicos a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.