Other times, the learning is painful because the code is nearly impenetrable, as if the person who wrote it in the first place didn't care very much about those who would have to follow. The real key to writing code that is easy for some future programmer to follow is to commit consciously to writing quality code. You have to understand what quality code is, you have to know a set of techniques for writing quality code, and your projects need formal methods to check code quality. This column will get you started. Code is the only authority You first have to accept the idea that the code, the stuff the compiler eats and turns into an executable, is the only authority.
Comments are nice, but they have nothing to do with what the program actually does.
Comments don't get compiled or interpreted. There is no guarantee that the comments you put in the code today will get updated to reflect changes made tomorrow. As a result, comments are often as dangerous as they are helpful. Design documents really fit into the same category. They get lost.