Let’s face it, we have have been writing software for decades now. We can no longer claim to be a new domain and pass-off nascency as an excuse for shipping sloppy code.

Most of us can tell the difference between good code and bad, but how do we go about creating beautiful software instead of merely reading about it?

Well, let’s make an attempt here.

IX Citadel.

This article is not going to teach you the zen of software maintenance. Rather it is just a dump from memory, sorted in pseudo-random order to ensure data persistence. Hopefully, some value is realized along the way.


Empathize through code

Speak so others will listen … write so others will read

There is elegance in brevity. Code golfing might help you win JS1k, but the lines-not-written will always be missing. The empty chasms serve as bigger obstacles to collaboration than the longest of obfuscation blocks.

Even when writing a simple wrapper for data retrieval, I have always found it useful to leave comments as markers along the trail. A few well-placed comments can save numerous man-hours of backtracking and spelunking, especially in highly collaborative teams.

When the number of developers involved, n, exceeds one, the need for clarity becomes non-negotiable for large projects. The catch is that n is not an instantaneous measurement. Even if it is the same person reviewing code a few months later, n becomes greater than 1 and the rule still applies.


(Don’t) Rewrite to update

Projects which neglect the need to be inclusive rarely get updates. Rather, functionality updates and even minor fixes are delivered via system rewrites.

Like many programmers, I sometimes jump to write fresh code rather than read old ones. This may be understandable as a side-effect of not following the previous section, but it is still a sub-par decision when developing software.

Old code probably comes with many guarantees that your new solution does not. For one, the existing code works, while yours is still in the theoretically-faster domain. We have version control software for a reason, use them.


Delete your way to perfection

Every block of stone has a statue … the task of the sculptor is to discover it.
– Michelangelo, probably

Be proud of removing lines of code. I look forward to days when my git commits show more red than green. Verbosity is a not a required dependency for clarity. In fact, clearing out no-longer-relevant decision paths and trimming circuitous execution cycles improve readability and reduce the search space as future bugs emerge.

If your manager ever asks you how many lines of code you have added to a project, I have only one piece of advice — run; fast and in the opposite direction.


Abstractions are not forever

We all love abstractions, they save us from repetition, allow us to stand on the shoulders of giants and are the secret to becoming a 10x rockstar-ninja. Okay, jokes aside, I have to admit, abstractions are really valuable tools. They allow us to leverage existing code as assumptions that can be abstracted away when writing higher-level code.

However, you have probably also heard about The Law of Leaky Abstractions. If not, the link is right there, I’ll wait, Joel is a much better writer than me.

Understanding the costs of abstraction is a crucial step in the journey of a developer. Learning to look for hidden costs is a crucial step in growing as a programmer. The earlier the realization is made, the easier the wakening from deceptive fantasies.


One of my answers to Peter Thiel’s contrarian question is the opinion that the raw accumulation of directed practice becomes indistinguishable from innate talent.

By making a concerted effort to write better code with each passing day, my hope is to get to a point where developing software has a much tighter execution step from thought to silicon.


Originally published at hackernoon.com on October 18, 2017.