Tuesday, October 27, 2009

A Sutra for Naming Conventions

Many have heard of Patanjali's yoga sutra, Brahma sutra, Panini sutra etc. Literally it just means 'a thread'. But what is it really? What qualifies as a sutra? When does a sentence become a sutra?

It turns out, there is a definition of sutra. A sutra must exhibhit all 6 characterists to be called so. What are they? As usual the Sanskrit grammarians have come up with a verse that defines a sutra.

alpAkSharam asandigdham sAravat vishvato mukham |
astobham anavadyam cha sUtra: sUtravido vidu: ||

अल्पाक्षरम् असन्दिग्धम् सारवत् विश्वतो मुखम् ।
अस्तोभम् अनवद्यम् च सूत्र: सूत्रविदो विदु: ॥

Source: vaayu puraaNa (anytime before 500 BC)

alpAksharam - Concise
asandigdham - without any doubt ie unambiguous or should have a singular meaning that is conveyed
sAravat - meaningful, ie should not contain gibberish
vishvatomukham - Properly applicable
astobham - devoid of 'stobha' (kind of fillers in Vedic chanting) like hA hU
anavadyam - irrefutable (na avadyam - that which cannot be refuted)

people who know a sutra, know it so.

Now, how does this apply to a programming style?

One of the hardest thing to do in software development is to understand others' code. Every developer would have come across some body else code and claimed it as 'the ugliest piece of code ever seen in life'.

What is an ugly code actually? In general, a hard to understand, spaghetti type code can be considered an ugly code. Typically lot of confusion arises from what the developer is trying to convey by means of the names of variables, classes, methods etc. A novice developer names a variable based on what he or she thinks. An experienced developer names a variable as how a novice would understand it without effort. In general the Shakespearean quote "Whats in a name?" just does not apply to programming. A rose may smell the same even if its called dog-poop, but its definitely a code-smell if naming conventions are poor.

Lets see how each characteristic of this ancient definition sutra applies to naming convention.

alpAksharam: Must be concise.
For eg. age, firstName, addressLine1 etc.

asandigdham: Must be unambiguous.
Eg. temp: What does it denote? A temporary variable? temperature? template?
Eg. Either use 'login' or 'logon' everywhere, but do not mix.
Eg. getReg(): What does it return? Registration? Registry? Regular Expression?
Eg. code, date: What kind of code? What kind of date?

sAravat: Pithy; Meaningful; Should not contain gibberish
eg. clr; tmpk; fru; stp, lzp. Combining this with the alpAksharam and asandigdham rules - will give a proper meaningful name.

vishvatomukham: Properly applicable
For eg, a variable name must have a proper scope. Eg. avoid local method variables having same name as member variables.

astobham: Devoid of unnecessary characters.
Bad eg: intx, a_b_c; Believe me, there are programmers who do this just to confuse others.

anavadyam: Flawless; Irrefutable
A naming of a variable or a class must describe exactly what it says. Another developer should not be given a chance to say "Why didn't you name this differently such that it is understandable?"