[thelist] Coding standards....

[Matt Warden]

On 12/7/06, Chris Ditty <cditty at gmail.com> wrote:
> Can a few of you share your coding standards?  Below is what I
> currently have, but I am drawing a blank on what else needs to be
> said.

I do not have a sample document on this computer, unfortunately, but
perhaps if you still need it in a couple weeks when I'm back home, let
me know and I'll fwd one. Some comments in the meantime:

> Variables should be capitalized accordingly and for easy readability.
>         ie....myVar, dpsLookUp, qry_myApp

This is good, but your examples are going to encourage bad naming
conventions. What is the type of myVar? What is its purpose?

You could choose a style like one of these:

[typecode][descriptive name] e.g., iAgeOfMother
[typecode]_[descriptive name] e.g., i_AgeOfMother or i_ageOfMother
[object name] e.g. RemoteConnection remoteConnection = new RemoteConnection();

You would need to define typecodes. There are a number of standards
out there where you can steal these.

> Use stylesheets when possible.  It speeds up rendering and makes it
> extremely easier to change colors and other details from one location.

Just a language point: you want to avoid sounding soft. People aren't
going to want to follow your standards, and if you make it sound like
they don't have to (i.e. "when possible"), then they won't.

> Comment, comment, comment and oh yes, COMMENT!!!!  Comments help you
> and your co-workers know what you were thinking of wen you wrote that
> bit of code.  6 months from now, are you going to remember what you
> did and why you did it?

Comment how? Are you talking about inline comments or block comments
at the beginning of classes/programs/procedures/functions/etc? How
should I format my block comments? jsdoc format? Dont care? etc.

How should I format my code? Brace on the same line of an control
block starter, or the next line?

if (foo) {
  bar();
}

vs.

if (foo)
{
   bar();
}


Some points to consider:

1) Keep it short and simple (2pgs printed  max). People tend to go
overboard and no one reads the document.

2) The standards should inconvenience everyone (including you!) about
the same. Writers of standards tend to put their own preferences down,
mixing in some best practices here and there. This makes for a
disaster when you're trying to get people to follow the standards. It
seems to underlings like you are just imposing your preferences on
them and using your position of power to avoid the inconvenience they
will have in adopting the standards.

-- 
Matt Warden
Cleveland, OH, USA
http://mattwarden.com


This email proudly and graciously contributes to entropy.