Write Code for Your Replacement, Not Your Future Self

There are many articles you have surely read about maintainable code. Most of them make the point that you will have to come back at some future time and read your own code, so you should write your code in a way that you will be able to understand. This is wrong.

The problem with writing code for your future self or some other current team members is that you will be coming at the problem in the future with some domain knowledge. You may have been away from the code for months or years, but you haven't lost the knowledge you had when you first set out to solve the problem. Thinking in this manner will lead you to leave out crucial details that you assume everyone working on the code will already understand.

Instead, you should write your code, documentation, and design docs with the idea in your head that you will no longer be at the company, or will at least have been promoted, and that the next person touching the code will be a complete newcomer with little to no domain knowledge. Your replacement should be able to understand the concepts through the design docs and understand the logic through your code and documentation without having to call you to ask any questions.

This leads you to write better code and better comments. Your code comments should be limited to explaining the why of the logic (what is supposed to happen), the code should be expressive about the how. The exception is when it is unavoidable to write some difficult-to-parse code (it does happen), in which case you should write thorough code comments explaining why you chose to code it this way in addition to the normal "what is supposed to happen" comments.

Keep in mind that maintainable code doesn't mean code that you can maintain. If your goal is to move forward in your career, then you are hoping to not be the one maintaining that code in the future. Always write as if you are not going to be there tomorrow and you will thank yourself later.