Almost every program has them: Arcane scriptures shrouded in mystery. They are read by only the brave few who dare try to meddle with powers beyond belief. Even fewer actually understand what the scriptures do, but they do know that they are a vital part of the program they are working on. Hopefully the wizard who wrote them is still around and in that case it’ll probably be him that changes and corrects any errors originating from the code. Unfortunately in many cases the wizard has left the building and is off somewhere else creating even more archaic wonders of mystery, all the while his previous work gather dust and all knowledge about it is forgotten over time because the apprentices that are still around are so intimidated by the complexity that they are afraid to touch it.
Writing code that is easy to understand
Most of the time you will be working in a team with other people and a large part of the quality insurance will be code reviews. If they don’t understand what you have written, how are someone trying to fix an error or trying to change your code a year from now going to? But even if you are not part of a team you will benefit from writing code that is easy to understand. Code that is easy to understand is easy to debug and easy to rewrite, two qualities all good code should have.
How do you know if your write code that is easy to understand? Simple! Just review your code from a month ago, it should be easy to get in to and only take a quick read through to figure out what it does.
Programming with comments
Comments in code can be your best friend or your worst enemy. Finding a comment in the method description of that legacy code you are working on is very helpful, but what if the comment isn’t accurate any more. What if the legacy code was altered but the programmer forgot to update the comment after the code change? Suddenly you are building your understanding of the code based on something that might be wrong and you think you have been told the factual truth. This is the breeding ground for bugs of the worst kind.
You shouldn’t have to write comments in order to understand the code yourself or to explain what you’ve done to others, if you do your code is probably not very good.
How to write better code
Refactoring is your best friend when it comes to writing better code. By all means, write code quickly and efficiently when you have the solution in your mind. But after you are done, take a moment and look at your code to see if there is something you could do to simplify it.
Maybe some part of your method could be it’s own method? Give variables, classes and methods names that explain what they do. If you have a duplication in your code after you’ve written it, extract it into a method that you call twice instead. Did you write a test before you started coding? Great! If you didn’t, try to do it. Good code is often very easy to test.
Refactoring is something you should never stop doing. Every time you run into code that would benefit from a simplification you should refactor it before you leave. This will incrementally create better code throughout your code base.
Write simple code that hides no bugs, is easy to change and easy to test. Avoid having to write comments, they are a sort of duplication that will increase the cost of maintenance and be error prone. Refactor all code you have trouble understanding.
You have an obligation as a programmer to write legible code. You are after all writing source code not creating sorcery.If you like it, spread it.