

How to Write Reliable Code - Tim1776

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.
======
briandoll
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)

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.

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.

------
CyberFonic
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.

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.

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.

