Here are some of my personal computer conventions.

## File/Directory Names

Use no spaces: This is problematic in Unix and in URLs (it is translated as either + or %20). If possible, avoid dashes (-) and underscores (_). Definitely avoid all other non-alphanumeric characters. This will avoid having to encode those characters in many situations.

Whether the name is plural or singular is arbitrary but be consistent. I prefer singular because it is shorter. The Japanese are lucky since their nouns have no difference if plural or singular. EG: In English you have 1 dog and 2 dogs but in Japanese you have 1 inu v 2 inu.)

Names should be in PacalCase case.

• PacalCase case is visually more informative than name in all lower case or all upper case.
• PacalCase case is good because the directory or file name is either directly displayed or copied and pasted for display. With PacalCase case, all you'd have to do is insert the spaces instead of putting it in title case.
• Avoid abbreviations unless the abbreviation is completely clear and cannot be misconstrued.

Here are exceptions to the preceding rule:

• The first letter unless it is purposely not capitalized. EG: cmdDog v Dog.
• Acronyms. EG: IBM. Some strongly oppose this rule. EG: Ibm.
• Multi-word names. EG: BigDog.
• The directory or file is strictly used in code, in which case you should use Hungarian or lowerCamel case to save your pinky from having to hit shift. EG: /bin.

Linux/UNIX folks will say that they'd rather do everything in lowercase so they don't have to make the effort to hit the SHIFT key all the time. They will also argue about the inconsistency of the capitalization of words (EG: "download", "Download", "DownLoad", and "downLoad") especially since Linux is case-sensitive.

The following convention is more about filing than file/directory names. When filing media, a file should exist only in one directory except for a quick and dirty directory that has copies of favorite files (EG: /0best) and back ups or archives. Otherwise, the file should be accessed by pointers, shortcuts, aliases, etc.

## Coding

As soon as we started programming, we found to our surprise that it wasn't as easy to get programs right as we had thought. Debugging had to be discovered. I can remember the exact instant when I realized that a large part of my life from then on was going to be spent in finding mistakes in my own programs.
- Maurice Wilkes. Discovers debugging, 1949.
• Length is not a virtue in a name; clarity of expression is.
• Procedure names should reflect what they do; function names should reflect what they return.
• Most programs are too complicated
• Simple rule: include files should never include include files.

"Google Styleguide" [https://code.google.com/p/google-styleguide/]. Google style guide including C++, Objective-C, Java, Python, Shell, HTML/CSS, JavaScript, AngularJS, Common Lisp, and XML. Lots of tips and good info too.

"Code Conventions for the JavaScript Programming Language" [http://javascript.crockford.com/code.html]

When providing instructions for maneuvering through an app, use syntax similar to this example: Option X is usually set by choosing the Tools menu, the Options selection, and then the General tab.

To assist in debugging, code for clarity: Assume that you'll have to look at the code after you haven't seen the code in years.

If possible consider putting continuations on the same line for legibility. EG: Consider these two blocks; Some consider the second easier to read:

x =
"west " +
"wind " +
"blows";

y =
"west "
+ "wind "
+ "blows";


For comma separated values where each "value" starts on a different line, consider using leading commas (instead of trailing commas). EG: Compare these two blocks:

// Trailing commas:
obj = {
id: 2,
useAccessibilityFeatures: true,
name: 'demo', //This erroneous trailing comma is hard to spot
//    translateHelpTexts: true
};

obj = {id: 2 // Having an item in the same line as the brace helps with code folding
, useAccessibilityFeatures: true
, name: 'demo'
//    , translateHelpTexts: true
};


On the other hand, your text editor may have a convenient join feature. EG: Compare these two blocks:

// This block:
a,
b,
c
// Might get joined as:
a, b, c

// While this block:
a
, b
, c
// Might get joined as:
a , b , c


Note that an extra trailing comma is ignored for many cases in C (and therefore C#, Java, etc.). Your text editor may also have utilities for visually catching extra commas may not be as important. Your compiler or code checker may also check for missing commas too (EG: jslint.com). The main reason to avoid leading commas is probably because so much code is written without them. See http://www.sencha.com/forum/showthread.php?6796-Leading-comma-or-Trailing-comma-that-is-the-question., http://www.thatjeffsmith.com/archive/2010/12/trailing-or-leading-commas/.

Be judicious choosing between ' and ". Basically try to minimize the number of escapes. Of course some languages don't give you a choice. EG: In C# ' is used for char, while " is used for string. EG: Consider these two and note that the second is easier to read:

x = "<a href=\"" + url + "\" title=\"" + tip + "\">" + link + "</a>";
y = '<a href="' + url + '" title="' + tip + '">' + link + '</a>';


Regarding font or typeface.

• Factor 1: Monospace. Each character must be the same width. Patterns in code stand out more.
• Factor 2: Unambiguous glyphs. These glyphs (characters) must be clearly distinguisable from each other:
 ‘ ’ ' “ ” " o O 0 1 l I i
• Factor 3: Character set. In English, all source code is in ASCII: The data may have window-1252, iso-latin-1, or Unicode, but the source code itself is ASCII.
• Choices given the factors:
• Courier. Traditional and most common. Shows only windows-1252, so glyphs in other character sets will stand out. Serif with a typewriter look. Beware: Courier New looks like Courier but it has glyphs beyond windows-1252.
• Andale Mono. Andale Mono's is legible at smaller font sizes than Courier. It has glyphs beyond windows-1252.
• Arial. One of the most common font. Unfortunately not monospace. It has glyphs beyond windows-1252. Uppercase I and lowercase L are not distinguishable.
• Arial Unicode MS. The most common Unicode font. Unfortunately not monospace. Uppercase I and lowercase L are not distinguishable.
• There are other programmer favorites. Here are some:
• Consolas. Newer look. Nearly same story as Andale Mono, but smaller and clearer.
• Fixedsys. Older look. Nearly same story as Courier, but sans-serif.
• Lucida Console. Nearly same story as Andale Mono.
• Terminal. Older look. Nearly same story as Courier, but sans-serif
• "Top 10 Programming Fonts" [http://hivelogic.com/articles/top-10-programming-fonts]. Watchout! He's a Mac guy! Hehe.

Line length. Many recommend a line length max of 79 or 80 characters. This comes from the days when the ISO/ANSI screen size was 80 characters by 24 lines. Many command line interfaces (like DOS or Cygwin) max at 80 characters. Some editors have a limit on characters per line. Personally word wrap is everywhere.

Put a brief description as comments ABOVE a block of code because if the description is in the block and the block is code folded, then the description will not be visible.

// This is a fabulous function description
// and will be seen if code is folded.
function Yes() { ... }

function No() {
// This is a fabulous function description
// but will NOT be seen if code is folded.
...
}


## Identifiers

Barring specific needs of particular languages, environments, etc., here are my simple rules for names in code:

Use PascalCase if:

• A class to be instantiated. EG: new VectorSpace.
• Exposed "public" methods and properties of a class. EG: class Dog {public Name}.

Use camelCase or underscore_case if:

• An instantiation of a class. EG: var myCar = new Car("Toyota").
• Unexposed "private" functions and properties within a class. EG: class Class {private id}. Consider prefixing with private members with an underscore (_). EG: _secret_name.
• Most variables are short and camelCase is best. EG: userId.
• If the variable is a long, a join of multiple components, or Python, then consider using underscore_case. EG: qualified_providers_for_current_year.

Use ALL_CAPS if:

• A constant or static property. EG: ELECTRON_MASS.

These older conventions may apply especially to the Visual Basic family:

• Follow my File/Directory Naming conventions above.
• Use Hungarian notation. Of course some people hate Hungarian notation!
• Local scope: tlpObject, but must declare (eg Dim or var) locally.
• Parameter (for a sub/function/procedure): PtlpObject or ptlpObject.
• Module/Script scope: tlpObject unless both client-side and server-side variables exist. In that case use CStlpObject and/or SStlpObject.
• Global scope: GtlpObject or APPtlpObject.
• Constants: KtlpObject.
• Session: Session("Object"). Skip the tlp becuase these are all really strings.
• Controls: should be distinct from variables. EG: strX is a variable, while txtX is a text control.
• Query strings: short as possible. EG: Use strSerialNumber to pass into or receive from a query string, but use SN in the query string itself.
• Sub: SSub().
• Function: FtlpFunction().
• When calling subs, functions, or methods, use the parentheses after the name as much as possible.

### Case or Notation

Here are the various case or notation conventions. The terms are ordered to build on concepts (i.e. they're not ordered alphabetically).

Sentence case
Just like proper English sentences. First letter capitalized. All other letters are lower case except words that are unconditionally capitalized, such as proper nouns and "I". There may be a space or punctuation or both between words. EG:
This is an example, George.
Title Case
Just like proper English titles. Main words are capitalized, including the first word, the last word, the first word after a colon indicating a subtitle, and the word after a hyphen in a compound word. Do not capitalize the first letter of words that are articles (a an the), prepositions (of between under through, etc.), or conjunctions (and or, etc.). EG:
Notes on the Production of Essays in the Arts and Sciences.
First Letters Case
The first letter of each word is capitalized without exception. First Letters Case is easier than Title Case to imlement programmatically. EG:
Notes On The Production Of Essays In The Arts And Sciences.
runtogether case
Words are run together. EG:
lowercaseexample
UPPERCASEEXAMPLE 
InterCapsExample
intraCAPSexample
lower case
All letters lower case. EG: this example uses spaces thisexampledoesnot this-example-uses-hyphens this_example_uses_underscores main_left-big (hypens and underscores)
UPPER CASE
All letters UPPER case. EG:  THIS EXAMPLE USES SPACES THISEXAMPLEDOESNOT THIS-EXAMPLE-USES-HYPHENS THIS_EXAMPLE_USES_UNDERSCORES MAIN_LEFT-BIG (hypens and underscores)
InterCaps case
Aka BiCapitalization, Mixed case, Bumpy case, NerdCaps. Words capitalized and run together. First letter may or may not be capitalized. EGs:
firtLetterNotCapitalized (aka camel case, camelBack case, lowerCamel case, humpBack case)
FirstLetterCapitalized (aka UpperCamel case, Proper case, Pascal case)
ILoveMyIBM (Acronyms all UPPER case)
ILoveMyIbm (Acronyms capitalized like proper noun)
intraCAPS case
Word run together but one word is all UPPER case and the next word is all lower case. EG:
thisISanEXAMPLE
tallMAN case
For similar words that differ in one part, put that part in all UPPER CASE. This is common in the health care industry. EG:
pulmiCORT
pulmiZYME
underscore_case
Aka snake_case. Separate words with underscores. Note that some search engines see an underscore as a space.
hyphen-case
Aka dash-case. Separate words with hyphens.
Studly case
Aka L337. Any letter may be UPPER or lower case. The more random the "better". Letters may be encoded with numbers or characters that have some vague resemblance to the actual character. In my opinion, Studly case is more for atmosphere than function because it does not abbreviate and it doesn't make your message any clearer. EGs:
iS tHIs rEaLly sO cOol? (Is this really so cool?)
L|-|!z 5|_|(|<s (this sucks)
Hungarian Notation
A variation of lowerCamel case, but where combined word is prefixed with a short (usu. three letters) lower case name denoting the data types or class. EG:  strMyName (A string variable)
tlp
Three Letter Prefix. The short lower case prefix used in Hungarian Notation. The tlp is usually but not necessarily three letters long.

## Indentation

Indentation conventions are used for writing blocks of code for human readability. This comes mainly from Indent style [W].

• BSD/Allman style. This is used by Visual Studio .NET IDE. I think it wastes vertical space, but it's easier for an IDE to track. It's OK if the line before the block is unusually long.
while (x == y)
{
something();
somethingelse();
}
finalthing();

myfunction(
alpha, bravo, charlie,
delta, echo, foxtrot,
gamma
)
{
dostuff();
}

• K&R style. Aka One True Brace Style; OTBS, 1TBS. The most popular. Note that K&R actually use BSD/Allman style for functions because functions can't be nested in c (but they can in JavaScript!).
while (x == y) {
something();
somethingelse();
}
finalthing();

• BSD KNF style. Like 1TBS, but 8-space tabs are used for regular indentation, while 4-space tabs are used for line continuation. Silly.
if (x == y) {
if (somefunc('hello', 'world',
'foo', 'bar')) {
a = b;
}
}

• Whitesmiths style. Yecch.
while (x == y)
{
something();
somethingelse();
}
finalthing();
• GNU style. Note also the space between something and its parentheses. Yecch.
while (x == y)
{
something ();
somethingelse ();
}
finalthing ();
• Pico style.
stuff(n):
{ x: 3 * n;
y: doStuff(x);
y + x }
• Compressed style. Space is conserved, but the closing brace needs some management, especially for nested items.
while(x==y){
something();
somethingelse();}
while(x==y){
something();
if(z==w){
somethingelse();}}
finalthing();
• Obfuscated style.
while(x==y){something();somethingelse();}finalthing();


## Tabs v Spaces

In word processors, use tabs instead of spaces. This is because proportional fonts won't line up with spaces.

In code, the issue of tabs v spaces is much more complicated and opinionated! The only thing certain is that most programmers will code using monospaced fonts. See links like these:

It is suggested that "tabs" equate to a length between 2-8 spaces --pick a size an stick with it. A lot of Microsoft and Macintosh code has 4-space sized tabs(    ), while a lot of Unix code has 8-space sized tabs (        ). Some people have more complicated rules about how many spaces they use in depending on context. In some cases you can adjust the IDE to interpret hard tabs in different soft tab sizes.

"Tab" can be hard tabs (\t, Chr(9), etc.) or soft tabs (faked with spaces). Left side indentation with hard tabs saves on the amount of white space characters used. If you need to count "tabs" in order to see how deeply nested a block is, then it is much easier to count hard tabs than soft tabs. However, as the example show, if your code is viewed in an IDE (Integrated Development Environment) where tabs are sized differently, then the code can look bad.

EGts4. This example uses hard tabs (represented with   ->) and spaces (represented with .). Looks good... so far!

  ->if(x==3)  ->  ->// hard tab comment
->{...............// soft tab comment
->  ->func();
->  ->// hard tab comment
........// soft tab comment
->}


But what if it's moved to an IDE where the tabs are 8-spaces instead of 4? It looks screwy!

      ->if(x==3)      ->      ->// hard tab comment
->{...............// soft tab comment
->      ->func();
->      ->// hard tab comment
........// soft tab comment
->}


EGt4. This example is the same as EGts4 but with just hard tabs. Looks good... so far!

  ->if(x==3)  ->  ->// hard tab comment
->{ ->  ->  ->  ->// soft tab comment
->  ->func();
->  ->// hard tab comment
->  ->// soft tab comment
->}


But what if it's moved to an IDE where the tabs are 8-spaces instead of 4? It looks screwy!

      ->if(x==3)      ->      ->// hard tab comment
->{     ->      ->      ->      ->// soft tab comment
->      ->func();
->      ->// hard tab comment
->      ->// soft tab comment
->}


EGs4. This example is the same as EGts4 but with just spaces. Looks good... so far!

....if(x==3)........// hard tab comment
....{...............// soft tab comment
........func();
........// hard tab comment
........// soft tab comment
....}


But what if it's moved to an IDE where the tabs are 8-spaces instead of 4? It still looks great!

....if(x==3)........// hard tab comment
....{...............// soft tab comment
........func();
........// hard tab comment
........// soft tab comment
....}


EGts: One practice is "Indent good, align bad". Indent from column 0 and avoid using "precision" alignment because the tab size might be different in different enivronments. Using this practice, different users can freely set their IDE to the tab size they want.

Instead of this:
my_function (  ->parameter1,
->  ->  ->parameter2,
->  ->  ->parameter3) {
->x = 8;
->....// Comment under the 8
}

Try this:
my_function (
->  ->  ->parameter1,
->  ->  ->parameter2,
->  ->  ->parameter3
) {
->x = 9;
->// Don't try to get precisely under the 9
}

Whether 4-space (above) or 8-space (below), it still looks good:
my_function (
->      ->      ->parameter1,
->      ->      ->parameter2,
->      ->      ->parameter3
) {
->x = 9;
->// Don't try to get precisely under the 9
}


If the coder had used soft tabs instead of hard tabs above, the problem would not have arisen but other viewers would have to put up with the original coder's preferred size for soft tabs. While it may seem that the solution is to use hard tabs for indentation, and to avoid precision alignment, there are common cases for preferring spaces/soft tabs:

• When you frequently post your code. Some editors, especially over-the-Web editors, take multiple hard tabs and reduce them to a single space. On the other hand, how often does this occur?
• When your IDE automatically converts hard tabs to a soft tab. Often times these environments don't even allow hard tabs. On the other hand, this is only a problem if you have to port code into and out of such an IDE.
• The need to encode hard tabs in code. EG: \t is often used to represent a hard tab in a character string. On the other hand, if you are writing code that writes code, especially nested code, it may be easier to put in \ts instead of copying in multiple spaces.
• Sometimes you have to edit code in an editor (EG: Notepad) or viewer (EG: A browser's view source — Very common!) that does not allow you to modify the display of hard tabs. EG: Form most browsers, view source will always display hard tabs as 8 spaces. People will counter that code which is too wide because it has so many indents, needs to be broken up in the first place. However, there are situation where no choice is available (EG: You're editing someone else's code) (EG: You have to use Note pad in production). On the other hand, when you have to use that editor, you would also have the annoynace of manually typing or copying in 4 spaces per tab.
• The language has stringent whitespace rules. Easy: The tab v space issue is decided by that language. Python gets close to fixing these problems.

In general, whenever you get someone else's code, check their tabs and spaces before you use it. Problems arise when you are working on code written by multiple developers and the developers have used a different number of spaces for their tabs. As long as there is no confusion in the depth of nesting, do not try to adjust the code. It is usually not worth the time to fix and the fix process is prone to error. On the other hand, some people will diddle with the tabs and spaces anyway.

## Spaces

Avoid space on the INSIDE of punctuation. Put a space on the OUTSIDE of punctuation, unless its outside is just on the inside of something else. This has some similarities to proper English punctuation. EG:

Fred, the frog. Miles per gallon (mpg).
function dome(x) {
p = [a, b, {c: 1, d: 2}];
q = (x + 3) / 4;
for (i = 0; i < 5; i++) {
r = 6 * i;
}
}


Do use a space after commas. This is particularly important for word wrap, legibility, concatenation, etc. EG:

one, two, three; // Yes
one,two,three;   // No


Put a blank line at the end of all files. There are historical reasons but these days it is useful when you concatenate files.

Don't use spaces for connection string items. EG: Provider=SQLOLEDB; Server=W2Kacctg; Database=pubs;.

Don't use spaces for HTML attributes. EG:

<p class="banana" name="Equador">     <!-- Yes -->
<p class = "banana" name = "Equador"> <!-- No -->


Don't use spaces between a method and its parenthesis (EG: foo(3)), an array and its brackets (EG: bar[4]), or the like, but do use them around keywords in the language.

if (c == 5) {y = 4;} // Yes
if(c == 5) {y = 4;}  // No


There should be no space between the name of a function and the left parenthesis. There should be one space between the right parenthesis and the left curly brace that begins the statement body. EG:

function fun(x) {y = 4;}  // Yes
function fun (x) {y = 4;} // No
function fun(x){y = 4;}   // No


If a function literal is anonymous, there should be one space between the word function and the left parenthesis. If the space is omitted, then it can appear that the function's name is function, which is an incorrect reading. EG:

ontap: function (x) {y = 4;} // Yes
ontap: function(x) {y = 4;}  // No


Have one statement per line. EG:

++a;        // Yes
b = a;      // Yes
++a; b = a; // No


Put a visual gutter between a comment indicator and the comment. EG:

foo; // Yes
foo; //No
/* Yes
*  yes
*  yes
*/
/*No*/
-- Yes
--No, especially in MySQL
# Yes
#No
`

Page Modified: (Hand noted: ) (Auto noted: )