I've learned the most important key to making reliable software, a method that has served me well for over 20 years.<p>Follow this simple rule:<p>Write a comment for each line of code, making it a complete sentence to express a complete thought.<p>You should aim to write for two computers in parallel -- one is the CPU, and the other is between your ears.<p>Why does this technique work to make software more reliable?<p>Line-by-line comments serve as a kind of logical checksum for the code, such that if the code and its comment differ in function, then you know immediately that work needs to be done in that area. Often, a coding bug will be revealed as you are writing the comment that goes along with the code.<p>More broadly, line-by-line comments serve to hold the intellectual context and keep your mind connected to reality.
One solution for this is to use a programming language that is easy to comprehend at a glance, omitting unnecessary "line noise". Ruby is a good example of a very readable programming language, designed for programmer happiness (ie. those that both write and read code all day)<p>Secondly, a major problem with line-by-line documentation is that you will soon end up in a situation where the documentation does not agree with the code. A bug was fixed, but the comment wasn't updated or vice versa.<p>Additionally, what makes for good comments in complex systems is not "what" a specific line of code does. Good programmers can read the code they are paid to write in. A good comment identifies "why". Why is this code necessary, why is it being solved in this specific way, why should I, as a developer of this system, care about this code.
Someone once wisely said (wish I could remember who) that programs should be written for other humans to read and understand and only incidentally for compilers to translate. The program will be read a lot more by humans during it's lifetime than by compilers.<p>Line by line comments can be hard to read. It helps to use clear naming, nouns for things, verbs for actions, spelling stuff out in full. I prefer block comments which only explain what isn't obvious in the code and what could not be expressed more clearly in the code.<p>As for comments not agreeing with the code, that should get picked up during peer review. Of course, the best comprehension test is when you come across the code a year later to make some change.