Coding Conventions

How to use this document:
  1. Read the General section (all of it)
  2. Read the section on the particular file type you are interested in
  3. Rules cascade. That is rules are applied with precedence general to specific (with specific having more precedence). So, e.g., if no file naming rule for a particular file type then it derives from rules in general section.

Contents

  1. General Rules
    1. Definitions
    2. File Names
    3. Layout
    4. Xml Layout
  2. File Specific Rules:
    1. N(Ant) Files
    2. Xsl Files
    3. Html Files
    4. SQL
    5. Code
      1. Common
      2. C#
      3. Java

GENERAL RULES

Definitions

UCC
Upper Camel Case naming: e.g. UpperCamelCase. Note acronymns should only capitalize first letter e.g. XmlFile not XMLFile. This applies even if acronym only has 2 letters e.g. UI (user interface) would be Ui.
LCC
Lower Camel Case naming: same as but first word does not have first letter capitalized. e.g. lowerCamelCase
LCU
Lower Case Underscore: words are all lower cased with underscore and word separator

File Names

  1. LCU: all lower case with word separator '_'. Version numbers should be separated with '.'
  2. Directory Names all lower case with underscores.

Layout

  1. Always use tabs rather than spaces.
  2. Tab-Spacing: 2 (Since using tabs rather than spaces this is not that relevant as individual users may configure tab spacing as they wish. However when needed for considerations of alignment this value is relevant).
  3. Wrapping (line 80 rule??).
  4. Content/Block braces should start on a new line e.g.: 
    // java/c#
public void foo()
{
...
}

// css
td.large
{
...
}

XML-Type FILE LAYOUT ((X)HTML, XSL, XSD, XML General etc)

Layout

This applies to all xml type files including: (x)html, xsl, xsd, ...

  1. All files should have striped appearance. This is obtained by correct indentation. This is as follows:
    1. After an open tag: 1. CR (Carriage Return i.e. enter key) 2. indent 1 tab stop. This applies no matter what the content of the tag (text or other tags).
    2. On end tag: content (being text and not another tag): 1. CR
    Example: 
    <Root>
	<Melville>
		was a man....
	</Melville>
	<Moby>
		<Dick>
			....
		</Dick>
	</Moby>
....
</Root>
    Some exception are allowed:
    1. need not always indent after root tag of document e.g.: 
      <html>
<head>
...
</head>
    2. Any tag whose content is text only and is short enough that it content + start tag + end tag fit on one line.
    3. Tags where internal content layout matters e.g. <pre> tag in html.

Naming Conventions

All names must conform to XML rules (e.g. rules for QNames - any normal element/attrib name must start with alphabetic or '_' and may contain only alphanumeric + '_'). Unless otherwise specified by schema/language should have:

  1. XML Elements:
    1. UCC
  2. Attributes:
    1. LCC

ANT BUILD FILES

XSL

Naming

  1. All templates named in LC with '-' as word separator (follow xsl: name conventions).
  2. Variables names are LCC. Prefix with g_ for global or put in a special namespace (?? http://www.openkf.org/xmlns/

HTML

  1. Certain inline tags in html need not have their content on a separate line. Tags such as: 1. <strong> 2. <em> 3. a tag etc

SQL

Layout

  1. Open bracket for a block on new line.

Referencs

  1. http://www.unc.edu/~jwatt/writings/naming_conventions.html

Code

Common

  1. Naming

    1. private member variables prefixed with '_'.

  2. Comments

    1. Summary comment on class obligatory.
    2. Comments on ALL public class members (exception: get/set).

C#

Follow standard conventions for that language. See Msft docs and the standard libraries.

Java

Java see Sun Coding conventions and conventions in standard libraries.

Comments

For recommendation on javadoc comments see [3].

References

  1. http://gee.cs.oswego.edu/dl/html/javaCodingStd.html
  2. http://www.infospheres.caltech.edu/resources/code_standards/java_standard.html
  3. http://java.sun.com/j2se/javadoc/writingdoccomments/index.html