Discrete Vector

Ever heard of the infinite monkey theorem? A smart guy called Emile Borel introduced it in one of his books on probability. It goes something like this:

“If you have enough monkeys banging randomly on typewriters, they will eventually type the works of William Shakespeare”

Well now that’s quite something isn’t it? This got me wondering: If you can get them to write a play, maybe we can get them to write code! Before you start panicking, let me rest assure you that what is stated in the theorem is, well, quite impossible. If I get the time, I shall try to do an edition of Code Widgets describing why.

But even though it is impossible for the primates to code like us, we have shown time and again that we are fully capable of producing the same ‘quality’ of code that they can. (But then again, if you pay people peanuts then… well, you get the point)

Writing great code is a talent; writing code that doesn’t look like Greek… well that’s an art.

In this edition of Code Widgets, we shall look at naming conventions used in C#. Naming conventions go a long way in writing clean, understandable and code that is easy to maintain.

Remember: the objective of your code should NOT only be to get the functionality working somehow. If this is your mind set, congratulations; you are well on your way to joining a long list mediocre programmers whose code is seldom read by fellow programmers unless there is a gun to their head.

The naming conventions described in this article are largely based on Microsoft’s suggested naming conventions for .net. Microsoft’s conventions concentrate largely on how classes and other public types should be named. There are some gray areas in it which I shall try to supplement using commonly accepted practices.

Hungarian Naming Convention

The Hungarian naming convention is dead. Well that is that and we can get on with our lives now. The practice of prefixing variable names with their types may have had its uses for a while but it soon became unwieldy. I mean who would want to remember a variable named lpszInterfaceLogFile. There are extensions to this convention that originated sometime around when VB became popular. This included prefixing all variable names with three letter types such as strName (come on admit it, how many times have you used this in C++?), arrItems for array of items. Then people started prefixing EVERYTHING with three letters such as database tables with t_ or tbl_ ! I mean, come on, if you hadn’t prefixed it would you have mistaken the name for a… window handle?!!

Microsoft itself has given up on this convention. So what this means in .net is, well, sensible looking variable names. a variable name to store a user name would simply be userName; no str prefix, no sz, nothing.

Casing

The first thing to remember is casing. .net follows both Camel casing and Pascal casing. Camel casing specifies that the first letter of your identifier should be in lower case. If the identifier consists of more than one word, the beginning of each other word should be in upper case.

For eg: myUserAccount

Observe that m is small and U and A are caps.

Pascal casing is similar except that the first letter is capital. The rest of the words follow the same rule as camel casing.

For eg: GetUserAccountInformation

Observe that G,U,A and I are in uppercase.

Class names, structs, enums use Pascal casing whereas method parameters, local variables use camel casing.

Acronyms/Abbreviations

Use only well known acronyms such as html, xml etc. You should use camel or Pascal casing for acronyms that are more that two characters long.

So htmlDocument or HtmlDocument instead of HTMLDocument

Two letter acronyms should be capitalized.

So diskIO NOT diskIo.

There is a popular argument going around regarding the fate of ‘ID’. Should it be batchID or batchId? Since it has only two letters it might seem that batchID is the correct version. But this is not the case. Contrary to popular belief, ID is an abbreviation for identification and not an acronym. Hence it should be batchId and not batchID. Hope I have cleared this for once and for all. Arguments are welcome as comments.

Avoid abbreviations at all costs for variable names and methods. Abbreviations cause a lot of confusion, are hard to maintain and makes no sense to anybody except you. A month down the line it wouldn’t make sense to you either!

So instead of InitSrvHandler(), you should expand it to InitializeServerHandler(). Don’t try to save on a few keystrokes at the cost of clarity.

Underscores

The rule for using underscores is simple: Don’t use them. Ever. The only exception for this rule is for private class members. Private class members should use camel casing prefixed with an _(underscore). This also means that the C++ convention of using m_ has been discarded. Good riddance!

Spell Check

I despair when I see code that is rampant with bad spellings. It shows how careless and disinterested you are with the code you are writing. Sure, theoretically anything can be a variable name. It doesn’t have to make sense. After all, the compiler doesn’t give a fig whether you name a method FormatFile() and FomatFile(). But think of your poor fellow programmer who might need to make sense of your code. I have lost track of the times when I take a glance at a method I need to call, assume that it is spelt properly and go ahead and use it, only to get a compilation error saying the method has not been defined.

So the rule is that every word that makes up your variable name should ideally be a word in the dictionary. Exceptions can be made for product names, feature names, acronyms and such. But for God’s sake don’t make mistakes in the words you invented!

Constants

So, you name constants like this: MY_SPECIAL_PORT_NUMBER. Well that’s simply great. Let me give you some friendly advise: STOP USING SCREAMING CAPS FOR CONSTANTS! Ooops, did I just shout? I hope that settles it. Constants should be treated like just any other variable: use camel case if its a private variable and Pascal case if its public. No prefixes or suffixes to denote that its a constant.

Public Methods and Properties

Public methods and properties should differ by more than just their case. This ensures that they are accessible from case insensitive languages like VB.net.

Summary

Here is a quick summary of the naming conventions to be followed for different types.

Classes: Pascal Casing. Should NOT be prefixed with a C. Should NOT have the same name as the namespace in which it resides. Do not use abbreviations.

Interfaces: Pascal case. Prefix with I. Class naming conventions apply.

Enums: Follow class naming convention. Do not prefix of suffix the enum with the word ‘enum’.

Delegates: Pascal casing. Add the word Delegate to the end of the name.

Exception classes: Pascal casing. End the class with the word Exception. Class naming conventions apply.

Event arguments: If you are defining your own event arguments class that inherits from the EventArgs class, end the class name with the EventArgs. Class naming conventions apply.

Class members: camel casing. Prefix with an _ (underscore).

Method Parameters: Camel case.

Method variables: Camel case.

Properties: Pascal case.

Public members: Pascal case.

Well there you have it, the most commonly used types and suggested naming conventions. If you think I have left out any that are commonly used, add a comment and I shall update the article.

Code Safely
Alex