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?"

6 comments:

Sathya Srinivasan said...

Very concise definition of naming convention indeed! I would say the same would be applicable even in more abstract concepts such as interfaces and services. After all, they share the same root.

Sathya Srinivasan said...

So, I have been reading Brahma Sutras, in fact a commentary by George Adams, which looks into what BAdrAyana's viewpoint is.

Given this definition of a sutra, can we really say that the 'gem' of sutras - the Brahma Sutra - is really a sutra?

While it satisfies 6 of the 7 qualities, you can hardly say that it is unambiguous, given the 22 different bAshyas given by various scholars.

So, is Brahma Sutra really a sutra in the strictest sense?

Vasu Srinivasan said...

@Sathya Srinivasan

Have to think about it. I think the sutra itself is unambiguous in the sense that it is not contradictory. But the interpretation is not. Tattvamasi vs Atattvamasi. Who knows what these mahaatmaa-s know, simple beings like us cant understand.

sachin said...

Brahma Sutra is a sutra. When the definition of sutra says it should be unambiguous, it means that it should be clear in meaning, at least once you have studied the commentary.

Sachin

Mohan Suswaram said...

Does the definition of sUtra occur in vAyu purAna or padma purAna?

Regards
Mohan Suswaram

Vasu Srinivasan said...

@Mohan Suswaram: Its possible that its in both. Several puranas do have overlapping sections.