Conventions by George Hernandez

Here are some of my personal computer conventions.

File/Directory Names
Coding
Coding Naming Conventions
Case or Notation
Indentation
Tabs v Spaces

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.
- Google sees dashes and spaces in nearly the same way, but sees underscores as a character. However, this section is not really about search engine optimization (SEO).
  - Compare:
    - google.com/search?q=Star+Wars. Sort of like a single keyword on the concept.
    - google.com/search?q=Star-Wars. Sort of like two keywords.
    - google.com/search?q=Star_Wars. The underscore is treated like another character.
  - Refs:
    - mattcutts.com/blog/dashes-vs-underscores
    - perspectiveondesign.com
    - searchguild.com/tpage18367-0.html
    - ihelpyou.com/forums/showthread.php?s=&threadid=8271. Also discusses how Google sees a few other characters.
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 must be in UpperCamel case.
- UpperCamel case is visually more informative than name in all lower case or all upper case.
- UpperCamel case is good because the directory or file name is either directly displayed or copied and pasted for display. With UpperCamel 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.
- 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.
Note that some UNIX or c guys 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 such as "download", "Download", "DownLoad", and "downLoad". But that's what they get for using a case-sensitive system!
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

When providing instructions for maneuvering through an app, use syntax similar to this example: This option is usually set by choosing the Tools menu, Options selection, and then General tab.
To assist in debugging, code for clarity: assume that you'll look at the code after you haven't seen the code in years.
If possible put continuations on the same line for legibility. EG: Consider these two continuations:
```
var strX = 
	"west "+
	"wind "+
	"blows";
```
```
var strX = 
	"west "
	+"wind "
	+"blows";
```
Whether you put a space between operands and operators (EG: color=red versus color = red) is a matter of consistency and legibility. Usually you use spaces to form little groups.
- Don't use spaces for HTML attributes. EG: <p class="banana" name="Equador">.
- Don't use spaces for connection string items. EG: Provider=SQLOLEDB; Server=W2Kacctg; Database=pubs;.
- Don't use spaces for CSS attributes. EG: style="color:red; font-size:1.1em;".
- Do use spaces for assignment operators, esp. when the right side is large. EG: cnn1 = Server.CreateObject("ADODB.Connection").

Coding Naming Conventions

Note that most of these apply especially to Visual Basic and/or VBScript, but other languages may have more language-specific conventions.

Follow my File/Directory Naming conventions above.
Use 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.

Follow the above for JavaScript, Java, c, c#, etc. except for the following:

Use camelBack Notation.
Constants: tlpALLUPPER.
Sub: There's no such animal.
Function: funtion(). Skip the tlp because functions can be overloaded (return different data types depending on parameters passed).

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 lower case except words that are unconditionally capitalized, such as proper nouns and "I". There is a space and or punctuation 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. 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. EGs: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.EGs: 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
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.

while(x == y)
{
    something();
    somethingelse();
}
finalthing();

K&R style. Aka 1TBS (One True Brace Style). The most popular.

while (x == y) {
    something();
    somethingelse();
}
finalthing();

Whitesmiths style. Yecch.

while (x == y)
    {
    something();
    somethingelse();
    }
finalthing();

GNU style. Note also the space between something and it 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! Precision alignment is with spaces is possible in code because almost all code is done in mono-spaced fonts.

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 ( ).

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

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

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

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

As you can see, only EGs4 translated perfectly!

The trick is 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 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.

Page Modified: (Hand noted: 2007-10-04 21:40:01Z) (Auto noted: 2007-11-17 06:33:24Z)