Coding Standards: Do It My Way or Else

The time has come, once again, for the dreaded coding standards committee. I don't imagine this conversation - I lived it. Every other year or so someone resurrects this tradition. And then utterly fails to accomplish anything useful. Why?

Coding standards solve the wrong problem. All of those discussions about placement of braces, number of spaces to indent, and routine comments mask the underlying issue - your application is complicated! These minutiae are merely fire and motion discussions. You spend so much time focusing on the bullets whizzing overhead that you never shoot back at the enemy.

Don't believe me? Then why does some form of the standards committee meet every other year? And they discuss the very same issues again and again?

The problem is understanding. Your company drops you into another module/package/program with no training. And you spend a lot of time just learning those little intricacies that build up over the years. How do we cut the learning curve?

Coding standards won't improve understanding. How about comments? Every programmer in the world knows to comment their code. And we get beautiful gems like this:

if x then
  #if condition is true
  [do something]
end if

Writing good comments is very difficult. Now I'm really going off the deep end. Comments are difficult because we write schizophrenic code. In code review, the two biggest non-technical issues are readability and performance. We balance writing code for the computer versus writing code for the human maintainer. Two audiences: human and machine.

Humans and machines understand differently. Go figure, who knew. People read code differently than the computer does. Actually, people have noticed. Coding standards and comments all try to fix one common defect: a person and the computer have to understand the same thing.

Think about that for just a second. People and machines process the code in opposite ways. Yet we're trying to write code where both have optimal understanding. So we move in opposite directions, hoping to reach the farthest distance in both directions. Compromises don't work that way.

Literate programming addresses this problem by organizing code both ways. It provides a framework for writing human oriented code. Then re-arranging it for the computer. You write the program for people. And then instruct the compiler in the most efficient arrangement.

Imagine yourself writing functional specifications and then adding the code right there. Link the code directly with the specification. Seems like the best comments money can buy.