Coding conventions part 1 : Naming Things

“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.”

—John Woods

At some point in the life of every programmer comes a time, when he/she realize that the way he/she organize code sucks(I have this moment like every day). And it's time to change few things and start caring about the organization and readability of code.
Code organization is crucial part of software development. Because software is not something which is developed from scratch again and again (as it will cost both time and money) but is updated and maintained for as long as it is possible to do so(this is why we have code re usability thingy). Programmer of special breed that is “Software Maintainer” is assigned this task. These are some of the most calm people in the industry because most of their salary is spent on Anger Management (May God bless them). If a code is poorly organized then more time is spent in refactoring it then actually updating or adding new features into it and it is also hard to debug(act of finding and removing bugs). Which can result in delays in software releases as well as can cost a lot of money. In the worst case scenario whole software might have to be rewritten from scratch.
At Stream of Bytes, I am committed to make life of Code Maintainers easy(and guarantee your safety from their anger). Hence, this post. This post is part of series of 3 posts which try to touch different aspect of Coding conventions viz. Naming, Aligning and Dividing code. As title of this post conveys, I am going to talk about some Introductory stuff and Naming different sections of Code.
Coding conventions are rules and methods for organizing(beautifying) code to increase its readability and easy maintenance. There are many of them however we are only going to talk about most famous ones(I have read all of them and chosen the popular ones, here's an entry from Wikipedia about it Wiki Article).

Coding Notations:

The Camel Notation and it's dialects:

Camel notation is inspired from camel's body shape. Idea is to make starting character of first word in a series of words either capital or lower case and then make case of first character of each consecutive word exact opposite of first one(like humps on body of camel). This makes word identification easy. Some examples:

• camelNotation: This is ordinary camel notation.
• CamelNotation: All capital came notation(commonly used for naming classes).

The Hungarian Notation:

Hungarian notation(Aka sigil notation) was invented by Charles Simonyi, a programmer who worked at Xerox PARC circa 1972–1981, and who later became Chief Architect at Microsoft®. It is inspired from the way Hungarian people write their name i.e last name first and first name last(voop!). In Hungarian notation we start name of an entity by first placing some special characters giving information about type of that entity. Here are some examples:

• System Hungarian(used in windows API(c, c++)):
  • dwLightYear: LightYear is a variable with size double word(16 bytes if word is of 8 bytes).
  • u16Hello : Hello is a variable storing unsigned integer of size 16 bytes.
• App Hungarian(original Hungarian notation):
  • sFirstName : sFirstName is a variable storing string(‘s’ as prefix).
  • cWords : cWord is a variable storing count of words(‘c’ as prefix).

Underscore Notation:

This one is on the list because of its heavy usage in C, C++ standard libraries. The idea behind it is pretty simple and straightforward. Just place underscore(_) where space is required and you are done. Some examples:

• count_words : This variable is storing count of words.
• __internal_bar : Variable name starting with two or more underscore are usually internals defined by compiler.

Naming different components of code:

Naming Classes:

Classes are blueprint of objects. They are like entities and in real world we use ‘Nouns’ to name entities like dog, car etc. Thus, always use nouns to name classes.If class is abstract use abstract nouns else use fully qualified name. This is the best way to name user defined data types. And as far as naming notation is concern you can use all upper case(class OutputStream {...}) Or follow the way used by standard library that comes as part of language. Some examples:

• abstract class Animal{..} : An abstract class to act as base class for animals. See, we use abstract noun here.


• class Turtle{..} : A class to represent turtle; This turtle. And as it's not abstract it uses non-abstract noun.

Naming functions

Functions are like used to divide a series of statement into logical blocks. In real world to indicate something is being done by something we use verbs right?. And there's no one stopping us from doing so in programming. Hence, Idea is to name function as {verb+object}. Some examples:

• fun setName(arg) : This one clearly indicates that this function sets Name.


• fun toggleLight() : This one is controlling some light and as it name tells us, this function takes nothing as an argument(with exception in case it's a global function and takes Light object as an argument), returns nothing and perform a binary operation on Light which implies that light has two states viz. On and Off, which is true according to real world.


• fun isLightOn() : This function is of form of query function and it queries about whether light object is on or off. Now, this case is exceptional one because ‘is’ is probably not a verb and the name is of form {question+object}. Where it is used? Simple when return type of function is Boolean.

Naming variables:

Variables are very crucial because most of the programming is saving data in variables and then manipulating them, using them for conditional branching and at last print or using their values. Variables are of two type constants(immutable) and non-constant(mutable). For languages which do not have type(ing) system, use App Hungarian as it will provide a lot more info about variable otherwise use camel notation. Always use descriptive names for example use ‘row’ and ‘col’ for accessing a matrix object(2d array) rather than ‘i’ and ‘j’. Some examples:

• sSocialSecNum : This one clearly indicates that this variable is holding a string which is Social Security Number.
• PI : Use all caps and underscore for spacing for constant(immutable) variables.
• nameOfCustomer : Camel notation for normal variables.

Okay, that's all for this one. I know that I have left out some other things such as pointers, pointers to functions, macros etc. Those will be explained in future posts. If you have any question you can ask them in comment section or at Stream of Bytes's Facebook handle and I will try to respond ASAP. And do follow this blog(show some love naa ❣). Have a nice time.

Labels