The Goal of Every Developer

As a software developer, you have one job: write code that other developers can read and use.

It sounds simple, but I would estimate about 90% of developers don’t follow this principle. That’s because it’s not really that easy.

Many new programmers think that writing code that works is the main goal. That’s only about 10% of the job. Writing code that works is usually straightforward, especially if you have given some thought to the architecture of the system.

In fact, you are writing for other humans. As long as the syntax is correct, the computer (i.e. the compiler) doesn’t care about anything else. Other developers are your target audience. If it is a personal project that only you are working on, there is still another developer; that developer is you in the future.

As someone who has written a lot of code that ended up being “legacy” code, and has worked with others’ legacy code, I realize these are the minimum rules for writing good code:

• Write maintainable code. How to write code that is well-designed and well-styled is its own book — I recommend Code Complete or Clean Code — and takes years of practice to learn.
• Comment the code. Any non-obvious code should be annotated with what it does, how it does it, and why. This could be accomplished with normal comments, JavaDoc-like annotations, and language constructs such as type annotations.
• Document the code. Documentation is required outside the code files to describe how to install, use, and contribute to the code. Any API should be well-documented as well.
• Write tests. No tests means you’re just guessing that your code works.
• Leave the code in better shape than when you found it. Tech debt quickly disappears if everyone makes small, regular improvements to the code.

Nothing here is new, but I think most people have little empathy for others working with their code, which is too bad. Most code is going to end up being legacy code. If you do not write code for other people, then are letting your colleagues (or your future self) down.