Nails and hammers

30 04 2012

I’ve work on a few projects by now, by myself and part of a team, and through some painful experiences (some worse than others I’d say) I’ve come to realize that coding standards are important but often misused, misread and generally just miss the mark completely. Before I go on to share my current version I would like to make two personal observations concerning these things.

First and foremost, standards should be guidelines and kept SHORT. Short I say and short I mean, following from some very good advice here. A good heuristic then is that the document should be printed at most on a single side of an A4 page. Anything longer simply yields a standard that nobody would fully read, understand or remember.

A second point is that the standard document should actually be documents. There are different languages out there with different idioms and practices, a coding standard should be written towards the specific language that is used currently by the team. Of course some overlap would usually exist between these documents but that is to be expected.

Since I’m working with C# at the moment I’ve geared the standards document towards those practices that I feel are best used within its context.

Language: C#, dotNet v4.0

Naming Guidelines
*****************
* Use descriptive names, prefer longer meaningful names than shorter abbreviated forms.

* Use recognized forms for commonly occuring programming structures (loops, switches, etc).

* Use "CamelCase" for names of classes, methods and properties.

* Use "pascalCase" for names of local variables and method arguments.

* Use "_pascalCase" for private class variables.

Comments
********
* Do explain reasons for obscure, convoluted or complex code.

* Do comment debt and costs.

* Don't comment what the code can say.

* Don't leave in commented-out code, that's why we use source control.

General Guidelines
******************
* Use spaces not tabs.

* Hardcode as little as possible.

* Leave the code slightly better than you found it.

The last point of the general guidelines is one that has been referenced by many and in many places, I found it following one of the books by Robert C. Martin and it stuck. I always try to practice it in whatever programming situation I find myself in.

Well that’s it, quite short, bit barren but it serves me well (so far).

“I walk a thousand nights to change the world”

Advertisements