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

Actions

Information

2 responses

30 04 2012
Tatham Johnson

I very much like that last point. A simple statement like that in a coding standards document can help new hires implicitly understand that code ownership isn’t part of a team’s mentality.
The only point I would disagree on is an aesthetic one, in that at my current work we use the “mCamelCase” style for member variables, and I’ve found the code to be a lot more ‘quick readable’ without the weird characters in the text. (By ‘quick readable’ I refer to the process of scanning a piece of code quickly to get a feel for what it does, without analysing it line for line)

30 04 2012
shattenyagger

You’re writing C++ code at work aren’t you? 😀
Some parts of the standard document is language specific, mostly the naming conventions since every language has somewhat different idioms. I think you’ll find that the “_pascalCase” is more prevalent in the C# community (check out this book by Cwalina&Abrams).

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




%d bloggers like this: