A Developer's Guide to Writing High Quality Code
As developers, we all want to write code that is not only functional, but also easy to understand and maintain. After all, nobody wants to be stuck debugging spaghetti code or trying to understand someone else's convoluted solution. Here are a few tips I like to keep in mind for writing high quality code:
The first user of your code is another developer.
So embrace it and focus on developer experience. Think of other developers as your users. How are they going to use your code? What are they going to do with it in the future?
Write beautiful APIs that spark joy. ✨
Elegant implementation details may be impressive, but it's the elegant interfaces that people actually care about.
You're a designer. You design APIs, interfaces and abstractions to make the life of other developers easier.
So next time you're tempted to write that super clever solution that only you will understand, take a step back and think about the poor soul who will have to use your code. Are you making their lives easier, or are you adding unnecessary complexity?
Remember: Someday, you may have to understand your own code.
The only constant is change.
Embrace the change. Code evolves. It should never stand still. If it does, it's probably dead.
Write code so that it's as flexible as possible. Don't spend too much time over-abstracting your code, only to have it thrown away later because of some requirement changes. Prefer to write code that is more verbose but flexible, rather than code that is limited and hard to change or adapt.
Don't fear touching code.
Whenever you come across code that you're hesitant to touch because you don't understand what it does and fear breaking it: Touch it. Take the opportunity to dive in and try to understand it. Rewrite it in a way that makes sense to you.
Just make sure to have someone else review it to ensure that you're not the only one who understands that code.
Make it speak for itself.
Nobody likes writing documentation. It's annoying and always out of sync. Write code that is really easy to understand on its own, so you don't have to write documentation. Use abstractions and naming that make the code self-explanatory and avoid using abbreviations or jargon that only make sense to you.
If you know ABAP, you know what I'm talking about. I'm looking at you,
And if you need to write documentation for edge cases, try to keep it as close to the code as possible. This helps it to stay updated and makes it easy to find.
The worst thing you can do is to create a documentation page for code that changes frequently.
Note: This is obviously different for public facing APIs.
Keep it stupidly simple
Keep your code simple. Added code always results in added complexity. Using abstractions only hides complexity. The only way to truly remove complexity is to eliminate code.
It's tempting to add more and more tools and libraries to our projects, especially when they promise to make our lives easier. But the truth is that each one adds complexity and cognitive load. Do you really need to add that state management library? Remember: A new user (developer) has to learn and understand the whole stack. And the new developer might be you in two months.