On Writing

9/1/2026

Writing is difficult. It is a frustrating experience to have a thought that appears so clear in your head, but it does not come out that way on the page. Writing is a reflection of the state of your mind. The ability to articulate your thinking is proof of understanding. If you cannot explain a concept clearly to someone else then you have not mastered it. This is why writing is important.

Over the course of my programming career I have developed a sort of intuition on what makes good code. I attribute a lot of my success to this intuition. More and more I find myself being in a position of guiding more junior engineers. I review many more PRs these days than I did earlier in my career. In the world of agents and code generation, the skill of reviewing code has become much more important. My difficulty is that I want to explain my intuition to others in order to help them improve their own code. It seems very obvious to me that a particular method or class is not good, and perhaps others agree with me, but I cannot clearly explain why. It is not helpful to ask for PR changes with no explanation as to why. That leads to frustration, not learning.

To alleviate this, I’ve taken up the practice of writing short pieces about different programming principles. Some codebases I work on have a particular architecture with a guiding philosophy behind it. There are good practices that should be followed when writing tests. Code comments should follow certain principles. It takes a lot of effort to write these explanations, but I have found it to be very rewarding. When people ask me questions or when I ask for a particular change, I can reference this documentation as justification. It is also a great learning tool. If you can explain the correct way to do something and provide the reasoning, people are much more likely to internalize it. This improves the overall quality of codebases that are worked on by many teams.