Sometime it is not the programmers that don't know the benefits of maintainable code or how to write it, it is the culture that rewards short-term velocity instead of long-term reliability. I've seen <i>superstars</i> designing shitty system and writing messy code to workaround processes and policies to launch quickly, and as a reward, they are promoted like taking rockets. It would be really hard for others to not follow the same path as long as the company needs to make money. Long-term benefits are hard to demonstrate while short-term feature/product launches are so obvious.
From the opening of <i>Structure and Interpretation of Computer Programs</i> [0] there is the famous aphorism, "Programs are meant to be read by humans and only incidentally for computers to execute."<p>I've been programming for over twenty years. Try as I might to produce code that expresses the problem eloquently and succinctly to unfold the solution in the readers' understanding as they skim through the source... it has rarely ever worked. Firstly you cannot please everyone. And secondly, programs are not structured for pedagogy.<p>Writing maintainable code is a communication skill but I find the best skills are writing, speaking, and illustrating concepts in prose, specifications, white board sessions, chats, etc.<p>The technicalities of ensuring code follows some kind of style guide, design principles, etc plays a big part. But nothing will explain "why" or the big picture stuff quite like a specification or blog post in my experience.<p>[0] <a href="https://en.wikipedia.org/wiki/Structure_and_Interpretation_of_Computer_Programs" rel="nofollow">https://en.wikipedia.org/wiki/Structure_and_Interpretation_o...</a><p><i>Update</i>: added missing link
I usually have the opposite problem. I end up writing clean code because it's the only way I can keep everything in my head, and hence can keep things straight. But it does make me a slower programmer than others, since maintainability takes thoughtfulness, which takes time.<p>That doesn't seem to get rewarded in startups, because often times, your goal is to test the startup hypothesis--and you end up throwing away code anyway. I think only two of my code bases have survived to this day in my whole career.<p>I am convinced that it pays to be faster, since you have more times at bat trying out ideas. I have adjusted and found some ways to eschew clean up because it doesn't matter in the long run, but I'm still struggling to find the right balance after all these years.<p>Anyone out there have heuristics that helps them with this struggle?
>How often have you seen an algorithm expressed with such grace that it appears boringly obvious?<p>There is a perverse quality that I see in mostly junior engineers of not wanting the complicated thing to appear simple. I think it's probably a result of some ego and accomplishment and wanting others to know it was challenging. I'm not sure exactly but I've seen it a lot.
I found out that some fellow engineers do not want to write maintainable code, they instead want to write code that:<p>- follows SOLID principles<p>- follows Clean Code principles<p>- follows Hexagonal architecture principles<p>- ...<p>Sometimes such principles do lead to maintainable code, but, most of the time they don't (at least in my limited working experience of around 10 years). An example: If you duplicate code because at the end it seems to be the proper way to write a piece of functionality that will be easier to maintain in the future (and most importantly, it communicates clearly its intention)... well, that's a no-go for some fellow engineers because, somehow, that violates all or some of the principles they have read in some blog post owned by internet celebrities.
The challenge is, how do you teach it?<p>Like many writers, many coders think their code <i>is</i> readable and are resistant to feedback. They literally do not see the problem.<p>You can institute all the rules and guidelines you want, but they see it as friction and overhead and only do it because they are forced to.
Haven’t come across this before but I can see myself using this framework of how, what and why in the future.<p>Few thoughts…<p>How:
Talking as a mid level programmer, I can’t control the language of choice, I can’t influence the framework or the design. I can control how the individual piece of algorithm is written.<p>What: Apart from the function names, the main important thing here is abstraction. Abstraction is a long term game and it improves with your understanding. The abstraction you choose with a few weeks of exposure to the domain will be entirely different when compared to the person who knows the domain for 10 years.<p>Your abstractions can also changes with the exposure to the actual problem in hand. The more you go down the rabbit hole the more abstraction will keep changing.<p>I like what Kent says here… <a href="https://kentcdodds.com/blog/aha-programming" rel="nofollow">https://kentcdodds.com/blog/aha-programming</a><p>As the author says, it takes years to develop the overall taste but also it takes time to find the right abstraction for solving the problem in the domain.<p>Why: Never thought of comments as the why. I used to think of comments as what more than why. Simple but important distinction.<p>Thanks for the insights.
In other words, code should be eloquent, it should be as easy as possible to understand why it exists and why the way it is written is correct (or give information as to why the author thought it was correct).<p>Likewise, with regard to modularity, I like the take on codebases that optimize for deletion and not abstraction (after all, abstraction is only a tool, not an objective).<p>These two together make up for the best code IMO.
I've found that documentation is one of the first things to go when time-constrained in Sprints. The PM/PO or Team Lead will pay lip service to the idea of allotted time to documentation writing for each Story, but don't enforce that during planning. Nor do they call it out during Retros.<p>Heck, there's some devs, senior and junior, who don't realize the value of standard branch naming, ticket references in commit messages, etc etc. Or they'll pay lip service (again) to a conventions standard, but still continue to work the old way over and over.<p>The common thread among devs that I've spoken to is that they feel they aren't talented enough to write good docs, that they don't have time, and that they don't know what to write about. I feel like the team lead and higher-ups need to focus on enforcing standards for a few sprints to get everyone working on the same page.
I interviewed someone from China once who wrote code almost as I write prose.<p>FirstWeCreateAVariableCalledX.AssignItValueY().PassYtoPvalue();<p>Now imagine 10,000 lines of code written like this and done so in a way that was thoroughly impressive. The creativity alone was startling. I would do it a disservice to further explain.<p>Yes, her object names were ridiculously long, but it was the most readable code ever. It was like she combined the code and documentation together. I'd seen this neither before nor since, and it was strange and beautiful.
The hardest problem is to adequately foresee the context and the background knowledge future maintainers will have.<p>* Context will change due to modifications and added features in the surrounding code.<p>* One tends to overestimate how much background knowledge a future maintainer will have.<p>* One tends to misjudge which parts of the necessary knowledge will be externally available / still "obvious" in the future.
I took issue with this quote<p>> “Isolating complexity in a place where it will never be seen is almost as good as eliminating the complexity entirely.”
— John Ousterhout<p>If you can isolate the complexity in one place, it isn't complex. It means that it is definitionally simple and separable.<p>There are things which cannot possibly be isolated and they are complex. Examples are idempotency, things that deal with synchronization or time, resource management across multiple entities.<p>It seems pedantic, but this insight is remarkable in effective system design. If you figure out the inherently complex non-negotiables ahead of time, the rest of your solution becomes pipe-fitting. A large percentage of modern software these days is lost because they start with pipe-fitting and just move the complexity of their problem around endlessly, never identifying it.
Yes, writing maintainable code requires the ability to explain.<p>There is far far more to "communication skills" than explaining yourself very well, stuff like negotiation and persuasion and conflict resolution. Most of those are less relevant to writing code as much as to getting it accepted.
My experience has been, the next guy always thinks it's the last guy's fault. But actually the fault usually winds being that of the next guy - even when I was the next guy.<p>Programmers are impatient, we look at the code, the code looks <i>terrible</i>. We lay into with a hatchet and three days later, it works. But there's a very minor problem. You look at the problem, look at it again. Three more days and you've ripped out your code completely, done apologies to the ancestors of the last guy and finally his work and all the problem are solved.<p>And the comment? The communication? No one read them, they made no sense. But once you complete the code, you realize no other comments could have sufficed.
There is a parallel to this comment that is not much thought about in mechanical CAD: some designers use tools that get the job done, but the model breaks if you look at it funny. It is all too easy to fall in this trap unless management is willing to pay for models that are maintainable and not just quickly moved out the door. Asking engineers to use the "principle of least astonishment" and develop work others can maintain is difficult at first. It's inculcating the idea of model maintainability and then supporting it against budget constraints that takes the work.
Communication? Maybe. But in my mind it's more of a user experience. That is, someone else picks up your "product" (i.e., code), how easy - or not - is it for them to engage with that product?
I consider maintainability and readability related, but two different things. I'd expect maintainable code to be readable. However, I've encountered code bases that were easy to read, but hard to maintain. I mean that the code was hard to change after new requirements came up.<p>So when writing some code, a programmer needs to have some good understanding on how the business requirements might evolve, and design the code with that in mind, so the next programmer can not only easily read the code, but also change it in face of new requirements.
If you have one group of coders writing new functionality, and another doing maintenance work on the application, you have diverging interests. The "new functionality" people have an incentive to rush stuff, because bugfixes won't be their responsibility anyway. The most cynical way to do this is writing a lot of new functionality, put it on CV, and leave for another company.