Archive for the ‘Dev Pearls’ Category

Generic Coding Standards and Guidelines

January 5, 2013

Merging Conventions to Aid Readability thus Reducing Development Time

When programming in a mixed-language environment,
the naming conventions, formatting conventions, documentation conventions, and other conventions,
can be optimised for overall consistency and readability.
This may mean going against convention for one or more of the languages that’s part of the mix.

For Example…

in many classical Object Oriented and procedural languages,
routine names have an initial capital letter (PascalCase).
The convention in JavaScript is for routine names to have an initial lower case letter (camelCase),
unless the routine is a constructor (intended to be used with the new prefix).
When a constructor is invoked without the new prefix,
the constructors this will be bound to the global object,
rather than where it should be…
The functions execution context.
When invoked with the new prefix as it should be,
the function object will be created with a hidden link to the value of the functions prototype,
and the functions this value will be bound to the function object (where it should be).
Because this convention has a very important reason,
your team may decide to carry that convention across the other languages you use.

Refactor or Document Short, Hard to Read Names

I don’t know how many times I see code that uses very short names which make readability difficult.
What’s worse, is that so often there are many different names that mean the same thing sprinkled across the project/s.
Short, hard to read, pronounce, or understand names are rarely needed with the programming languages of today.
Use easily and quickly readable names where ever possible.
If you have to use short names or abbreviations, keep them consistent.
Translation tables are good for this.
You can have a commented translation table at the beginning of a file,
or at the project level if the names are wider spread.
Names should be specific to the domain your working in, rather than to the programming language.

Meaningful Loop Index Names

If your loop is more than a couple of lines long or you have nested loops,
make your loop index name something meaningful,
rather than i, j, k etc.

Additional Thoughts

  • Code is read many more times than it is written.
    Make sure the names you choose favour read-time over write-time convenience.
  • If you have names that are general or vague enough to be used for multiple purposes,
    refactor your code, maybe create additional entities that have more specific names.
  • Don’t leave the meaning of the name to guess work.
    This taxes the programmers mind unnecessarily.
    There are better uses of our cycles.
  • Agree on and adopt a set of coding standards and guidelines.
    It’s more important to have standards than to not have them because you can’t agree on the “right” way.
    They will save wasted time and arguments during coding, and code reviewing.

Keeping encapsulation on ones mind.

December 24, 2009

This is another of Steve McConnell’s (author of Code Complete) gems.
Do we do this?
If not, why not?

Anytime you find yourself looking at a class’s implementation to figure out how to use the class, you’re not programming to the interface; you’re programming through the interface to the implementation. If you’re programming through the interface, encapsulation is broken, and once encapsulation starts to break down, abstraction won’t be far behind.

If you can’t figure out how to use a class based solely on its interface documentation, the right response is not to pull up the source code and look at the implementation. That’s good initiative but bad judgment. The right response is to contact the author of the class and say “I can’t figure out how to use this class.” The right response on the class-author’s part is not to answer your question face to face. the right response for the class author is to check out the class-interface file, modify the class-interface documentation, check the file back in, and then say “See if you can understand how it works now. “You want this dialog to occur in the interface code itself so that it will be preserved for future programmers. You don’t want the dialog to occur solely in your own mind, which will bake subtle semantic dependencies into the client code that uses the class. and you don’t want the dialog to occur interpersonally¬† so that it benefits only your¬† code but no one else’s.