codehints

stuff about programming

Tag Archives: software

prefixes: using a consistent nomenclature system

I use prefixes for everything that I can: variables, constants, classes, files, methods, etc.

Typically, programmers use multiple nomenclature protocols:
1.  MyBlah       … camel casing
2.  myBlah       … camel casing, with the first-word exception
3.  MY_BLAH   … all-caps, which necessitates the inconsistent usage of an underscore
4.  _myBlah     … preceeding underscore
5.  myBlah_mc … suffix
etc.


On the other hand, here’s a code example that uses only prefix’s:
//———— actionscript ————————————-
package pkg_blah
  { // ‘pkg’ stands for ‘package’
    //     I’m a bit unhappy about using a multi-letter abbreviation for one-word
    //     nevertheless, using a prefix for packages helps to organize your work directory also.

    public class ec_blah
      { // ‘ec’ stands for ‘external class’
        //     from the flash point of view, classes are external;
        //     maybe simply using a ‘c’ is better for other development environments.

        private    var pvi_blah  : Number = 1.234 ; // ‘pv’ stands for ‘property variable’;
                                                                    // ‘i’ derived from integer, now I use it for any numerical type.

        private    var pvn_blah  : String = “Joe”   ; // ‘pv’ stands for ‘property variable’;
                                                                    // ‘n’ for ‘name’ … names are a uniquely special string sub-type
                                                                    //     maybe this is a bad exception, but for me it’s ok.

        private const pks_blah : String                ; // ‘pk’ stands for ‘property constant’; ‘s’ for ‘string’.


        private function om_blah ( args_blah : String ) : Boolean
          {
            // ‘om’ stands for ‘object method’
            //     I should probably use ‘pf’ for ‘property function’ instead.

            // ‘arg’ stands for ‘argument’; ‘s’ for ‘string’.

            const lko_blah : Object = { pva_blah : [ 0 , 1 , 2 ] } ;
            // ‘lk’ stands for ‘local constant’; ‘o’ for ‘object’.
            // ‘a’ for ‘array’

            var lvb_blah : Boolean ;
            // ‘lv’ stands for ‘local variable’; ‘b’ for ‘boolean’.

            lvb_blah = ( args_blah == “A” ) ? true : false ;

            return lvb_blah ;
        }
      }
  }
//—————————————————————–

I like the info that I can quickly get from prefixes; and I like the consistency of using only one nomenclature system: only prefixes.

I admit that I am inconsistent with my prefix system; however all of the inconsistencies DO FIT into one nomenclature protocol; here are some of my inconsistencies:
1. pkg_blah – I used a 3-letter abbreviation for ‘package’ ( ‘pkg’ ) instead of a 1-letter;
2. pvi_blah – I used an ‘i’ for numbers, which comes from the word ‘integer’
                    clearly 1.234 is not an integer, but I use the ‘n’ for ‘names’
                    so I had to figure out something different for ‘numbers’;
3. pvn_blah – I use an ‘n’ for ‘names’, even though it is a ‘string’, simply because names are used so often
                      in coding that it seems as if they are practically their own special data type.
4. om_blah – 2 bad things happen here: the ‘o’ here refers directly to the class/object,
                      but I did not include an ‘o’ in my class properties;
                      and I did not use a ‘p’ to denote that ‘om_blah’ is a ‘property’;
                      so technically I should call this ‘pm_blah’, but old habits die hard;
                      or I could have used ‘pf…’ which would probably be the best:
                      ‘property function’ which by definition is a ‘method’.
5. notice that I do not have a way of distinguishing private properties vs. public or protected; or static props, etc.

I am not suggesting that my prefix system is the perfect prefix system; but rather I am suggesting that using a single prefix system is better than using multiple systems. You might develop a prefix system that is cleaner than my prefix system.

Also, note that I like underscores. A lot of developers dislike underscores; I once used a system combining prefix’s with camel casing, and that worked pretty good … but be thorough with the camel casing if you do use it – no first-word exceptions and what not.



Here’s a javascript example:
<script type=’javascript’>
function gf_blah ( argas_blah )
  { // ‘gf’ = ‘global function’
    // ‘argas’ = ‘argument, array of strings’
    // etc
  }
</script>

the downside of de-bugging tools

Imagine this… One morning office workers arrive to find that their office building is leaning over. The boss calls an engineer about the problem who arrives and uses his de-bugger tool to asses the problem.

It identifies that the foundation of the building has cracked and partially collapsed; with this knowledge the engineer advises the boss to fix the foundation. The boss has a worker patch the foundation with new concrete and re-boot the building. The turn around for the fix is quick and cheap.

Everybody cheers.

But a month later all of the employees come to work to find that the building has collapsed completely. Why?



… because the real problem was missed. The original engineer, relying on his de-bugger tool, did not do a manual inspection of the foundation, or the building system to which it is attached, or anything else. If so he would have inevitably investigated many integrated and tangentially-related systems/components.

If he had he would have discovered:
1 – the foundation’s chemical composition is affected by high aridity,
2 – the bedrock beneath the foundation is connected to a small tectonic fault line 20 miles away.

And as it turns out, when these two factors rarely occur simultaneously, such as the other night when the air was very dry and the ground coincidentally shook a little, the foundation crumbles.



It’s interesting to note that if the engineer had done a lengthy exhaustive manual investigation, he would have learned much about the whole building system, and become a better engineer … and that is the point of this story: the process of manual inspection is an important part of the process of understanding how a system is built.

Students should never be shown de-bugger tools, much less taught to use them in the name of efficiency, because more often than not the efficiency that they attain with de-bugging tools is short-sighted-efficiency. De-bugger tools foster less-than-quality coding habits.

And lastly consider this: bugs are a measurement of the quality of your software’s architecture ( and an insight into the planning that went into it’s development ). Lots of bugs usually indicate a bad architecture; a company should reason with this. In my experience it is better, though depressing, to start over from scratch than to attempt to add lots and lots of band-aids to a badly built application.

%d bloggers like this: