Notes on Coding Style

Coding is much like writing. There are many, many conventions, and following these conventions leads to cleaner, more maintainable code. But every so often there’s a situation that calls for breaking the rules.

This lack of clarity has led to wars amongst passionate programmers. Tabs vs spaces, indents vs brackets, syntax sugar vs no syntax sugar, on and on and on.

I’ll quote fastai’s coding style:

Everyone has strong opinions about coding style, except perhaps some very experienced coders, who have used many languages, who realize there’s lots of different perfectly acceptable approaches.

I agree, there are many acceptable approaches. Just like how in writing there are many kinds of agreeable prose. For most programmers, it’s enough to develop a style of writing that’s agreeable to most. Even if you see this work as a craft, if you try and cut every program to perfection then you just won’t get much done. There’s a tradeoff between volume and quality of output, and too often I find myself leaning too hard into one or the other.

Over the years I’ve developed a few heuristics for “good enough” programming style. These are things I check and re-check for every line of code I write. Great programs won’t come about just from following these guide lines. But I have yet to see great programs that omits these guidelines.

  • Favor clarity. All parts of a program – the code, comments, and context – should make it clear what the program is doing and why.
  • Favor brevity. Short programs > long programs, short lines > long lines, short comments > long comments. It’s not always the case, but shorter programs tend to be more clear. There are just fewer opportunities to screw up and confuse your reader.
  • Avoid too much copy and paste. It is okay to copy and paste occsaionally, but if you abuse it you can end up with a big mess.
  • Think about “locality” of functions and variables. Often it makes more sense to readers when data and the functions that process those data are close to eachother in the file. Many times I have been confused by having to keep open 3+ tabs of editors. Sometimes they’re 3+ tabs of the same file opened at different functions in a 10k+ line mess. Avoid this.
  • Don’t repeat yourself. I have seem comments repeat logging statements repeat code. Don’t do this.
  • Too few comments and your program is obscure. Too many comments and I can’t tell what’s being excuted.
    • My rule of thumb has been to never let comments explain what is happening in the code. If you can’t tell what’s happening by reading the code, then re-write it.
    • Reserve comments for explaining why something is the way it is. In other words, to provide context.
  • Rewrite, rewrite, rewrite, rewrite! Just like in prose, the first draft should not be the last. You learn so much in the process of writing that oftentimes a rewrite is necessary to incorporate the new, better ideas learned. It is okay (albeit very painful) to scrap thousands of lines. Do it more often.