Eloquent Codebases #

From time to time you come across such a good implementation that it makes you stop and go explore it in depth.

You wander around for a few minutes, marvel at how well designed that code is, how easy would it be to refactor things if it were the case, how much thought went into keeping it within scope; then you realize that you still have work to do and go back to it while concluding that you would never be able to do such great work.

And you would be right because neither the author themselves think that they did great work. All they can see are the bugs that keep pilling up, the missing nice-to-haves, the trade-offs made in order to enable such eloquence. The same things that we all see in the code we write ourselves.

Most of the time we find these great snippets of code are within the bounds of language libraries, software frameworks or developer tools. More often than not, we fail to realize that the main purpose of these artefacts is to make the life of other developers easier. A thing of not much concern when you have to write code for an end product. Within this specific context, abstraction and other system building methodologies and techniques are not of much use.

When implementing details and workflows, encapsulation is more important than abstraction, performance is more important then covering all the use cases, solving problems now is more important than solving problems eventually. This is true because most of the features in a product are built once and even in the cases when a feature is similar to another one it is best to treat it as a new one. It will end up diverging anyway.

The way you iterate for a product is fundamentally different than how you iterate when writing a library or a framework. For a product you have to understand the user's problem, discuss possible solutions, implement these solutions, present a demo of the solutions, ask for feedback and repeat until a satisfactory solution is found. Even if the process for a library or framework is identical, the difference is that you are also the target audience which makes you elegible for making all these decisions required to reach the satisfactory end result thus making the process much faster and go through as many iterations as you want. The fact that you can use your own tools yourself to build products gives you an even bigger advantage when assessing what features are missing, how to implement them better and, more important, the way you would like to interact with these features.

Since assessing the quality of a codebase cannot be done by the same coding standards for all projects then it should be done based on the quality of the decisions made. Given a certain information, did you make the best possible decision? For example: when implementing an ORM, did you make the database access an abstract class? or, when implementing an onboarding, did you hardcode the two steps or built an entire workflow to implement just those two steps?

Making the right decision will shorten the time between iterations by creating an easy to extend library in the case of the ORM of by shortening the time it takes to implement in the case of the hardcoded onboarding leading to a shorter iteration time and a better end result.