Writing code is easy, every newbie can write a program after following a programming class. However, writing good, efficient and maintainable code is another story. And good programmers are as rare as tasty food in the Netherlands! And as a software developer, I probably spend more time understanding code (from others but also myself) than actually writing code.
For that reason and because in some domains, maintainability is a big deal, writing maintainable code really matters. When you write code in that industry, you have to keep in mind that it will be maintained by people that is not even on earth at that time. This is why I was interested by the book "The Art of Readable Code".
The book explains why we should write readable code and lists rules to help to write such code. The authors also provide examples of good and bad code blocks. Overall, the book is interesting and the topic is a good one but many parts are very long and go too much into the details. The authors really know what they are talking about and illustrate each paragraphs with sound examples but sometimes, it feels like reading the summary at the end of each chapter would be already enough to understand the principles.
After reading most of the book, the main focus is on the following aspects:
- Try to understand how people will read and understand your code. Put yourself in somebody else shoes and try to understand how he/she could see your own code and adapt the way you write code so that others will understand it. There could be many barriers between two developers (language, units, reasoning, etc.), documenting helps to "bridge the gap" between different cultures and habits.
- Identify and annotate code that need rework and explain why you write the code that way. In particular, if you do not finish to implement something, use a crappy hack, annotate your code using common tags such as FIXME, XXX, HACK, etc.
No matter what, you have to consider that you are no longer writing code for pleasure ("let's write 1000 lines of C code tonight to implement a program that draws naked kitties on my screen") but thinking about the impact of what you write on the long run ("how folks from a different country or in the next two generations will understand what I am writing"). Documenting your code, as writing efficient code is really important and have an impact on the long run, especially if it is supposed to be used for several years. The last days show a good example: some folks reported that Microsoft skips Windows 9 to ensure application portability because some applications use a dirty hack to detect the Windows version. Writing better code, documenting potential side effects would have helped.
Sure, since the last couple of years, development tools have improved and help programmers to write better code (follow coding rules, refactoring, detection of errors), but there are still some aspects of the code that cannot be fixed by the IDE (variable names for example) and that should be fixed directly by the development. This is why keeping in mind maintainability rules matter and will make you a better software developer.