Coding standards are communication tools

I’ve been writing a lot of C code over the past few months. It’s been fun and I’ve learned a good amount about writing solid, low-level, procedural code. While cranking out code I’ve also been developing a simple coding standard, mostly for my own use and based on on the K&R standard. I’m not working with a particularly large group (and probably won’t be anytime soon) so I won’t be asking anyone else to follow these standards anytime soon. They don’t follow the rest of the code 100% either. But even being essentially the lone hacker on the project, I’ve found sticking to a standard helpful.

C is a great language but often I want to say things as part of the program that I can’t put in the code. For example, there are often things about variables that aren’t captured by the type and even if they are, I don’t want to have to look up the type every time I see the variable to get that information. But by following simple rules about how my variables are named, I can pack in a lot of information. For example, a plural name is an array, a name prefixed with num_ indicates that it holds the number of something in the system, a name prefixed with rv_ means that it stores the return value from a function (probably for error handling). Outside of variables, function names are verbs, locally defined types meant to be private are CamelCased, exposed types have a _t suffix. Of course, these don’t apply in all cases and some amount of discretion is involved.

Following a standard like the above has a double benefit: first I can think less when it comes to naming things and it prevents casual naming conflicts. Secondly, as I hinted to above, it’s a communication aid. There’s a certain amount of information that is encoded into the language’s syntax and semantics. This layer is checked and enforced mechanically at compile time. But a coding standard allows for a secondary, optional layer that can convey more information without expanding the language standard (and allowing teams and individuals to develop their own, suited to the task at hand).

Note that I’ve mostly talked about naming conventions and I haven’t said anything about formatting. Personally I think formatting conventions are less important and helpful. It can be annoying to read code that is formatted differently across files (or in the same file), but I think the benefits to be gained from consistent formatting are less than that for consistent naming. In fact, I think that formatting issues should be eliminated by having a tool that will automatically reformat code to a single standard. I have the Go language’s gofmt tool in mind, but I’m sure there are others. (This is also one of the pet peeves I have with Haskell: it’s apparently really hard to write an auto-indentation tool for its syntax)

One caveat is that I have no personal experience as to what effect a coding standard has across a large group. I’ve found two articles arguing against coding standards on teams, but they’re both far too emotional and hand-wavy for me to take them seriously. Personally I would be wary of a developer who can’t adapt to a coding standard in a reasonable amount of time. That being said, there are definitely more important things than adhering to a standard (getting working code for one). However, I do think that coding standards fit into a larger culture and system of good coding practices. These include things like code review, appropriate use of version control and proper communication channels to talk about bugs and feature changes.

To conclude, a coding standard can be a great tool for personal uses. In some ways it frees up my limited mental RAM to think about more important things. It also allows me to pack more information into my code, outside of what the language syntax or semantics allow. I’m less certain of the benefits for large groups and as Emerson puts it, a foolish consistency is the hobgoblin of small minds. That being said, I’d like to believe that a good coding standard (with formatting mechanically enforced) along with practices like code review can lead to a higher code quality.

About these ads

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s