presentation on software documentation and coding standards

ByChirag Singhal

Presentation on Software Documentation and Coding

Standards

Concept:

Efficient yes, But Reliable and Maintainable first !

Purpose of Coding Standards and documentation :

• To Develop Reliable and Maintainable Code, we must follow Coding standards.

• The Coding standards, naming conventions mentioned here are compiled from our own experience and by referring to Microsoft and non-Microsoft guidelines.

• There are several standards mentioned in the world. None of them are wrong or bad. What is more important is, selecting one approach and ensuring that everyone is following it.

How to follow Standards across the team !

• Team of different skills and tastes !• Best approach is to have a Team meeting

and set our own standard document.• Discuss the Pros and Cons of each and

every point.• Everyone can have different opinions.• Important thing is to agree upon a

Standard you are going to follow.

Presentation categorized into two parts :

1. Coding Standards.2. Documentation.

1. Naming StandardsPascal Casing : First Character of all Words

are in Upper Case and the other words are in Lower case.

Example: EmployeeName.• Camel Casing: First Letter of Identifier is in

Lower case and the first Letters of each Subsequent letters would be capital else lower case. Example: camelCasing

• Uppercasing: All letters are in Upper Case.

1.1 Assembly, File Names and Namespaces

• Assembly Name should be self-explanatory expressing its purpose. It must start with uppercase and the first letter of the next word should be capitalized.

• The filename should be same as the class it contains.• Every class should be defined within a namespace.

Use Pascal Casing for namespaces, and separate logical components with dot. Each word after dot should start with Capital letter. Name should be unique.

• For naming namespaces, use the company name followed by the technology/department name tomaintain the uniqueness of namespaces.

Contd..• Example: Infosys. Intranet, Infosys. Web etc• Do not use the same name for a

namespace and a class.• Assembly Name need not be same

as Namespace name.

3.2 Interface names:• Use Pascal casing.• Similar names when you define a class/

interface pair where class is a standard implementation of the interface. The names should differ only by the letter I prefix on the interface name.

Example:public Interface IRemote{// Interface

methods are listed here}public class Remote: IRemote{// class

definition goes here}

3.3 Class Names:• Do not use a type prefix, such as C for class, on a class

name.• Example: use the class name FileStream rather than

CFileStream.• Use Pascal casing.• Use a compound word to name a derived class. The

second part of the derived class's name should be the name of the base class. For example, ApplicationException is an appropriate name for aclass derived from a class named Exception, because ApplicationException is a kind of Exception.Use reasonable judgment in applying this rule. For example, Clerk is an appropriate name for aclass derived from Employee. Although a Clerk is a kind of employee, making employee a part of the class name would lengthen the name unnecessarily

Contd..• There can be more than one classes in one

file so try to keep the filename same as the class which has entry point for the application, otherwise just give the name, which seems to be most appropriate.

3.4 Method Names:• Use the verb-noun method for naming routines

that perform some operation on a given object, such as CalculateTotalInvoice ().

• Use Pascal Casing.• Avoid using Underscore in method names

to separate words other than .Net framework methods. Example .Net framework has methods like Page_Load can have underscore.

3.5 Parameters Name:• Use descriptive names. It should describe

about the parameter more rather than its type. Example: Type GetType (string argName).

• Use Camel casing.

3.5 Constraints:• Constants should be written in upper case

letters only.• Underscore can also be used to separate

meaningful words. • The names should be self- explanatory.• Write comments if the names are not self-

explanatory. • Constants should be assigned value at the

time of declaration.• Example: const int NUM_DAYS_IN_WEEK = 7;

3.6 Variable NamesUse Camel Casing (documentFormatType) where

the first letter of each word except the first is capitalized.

Boolean variable names must start with “is” such as isFileFound.

Even for a short-lived variable that may appear in only a few lines of code, still use a meaningful name. Even for short-loop indexes use count instead of i.

Do not use literal numbers or literal strings, such as For count = 1 To 7. Instead, use named constants, such as for count = 1 To NUM_DAYS_IN_WEEK for ease of maintenance and understanding.

Do not use variable names that conflicts with Keywords used in .NET Framework.

Do not prefix the variable names with Hungarian type notation.ExampleUsestring userId ;Instead of  string strUserId;

4. Comments:

• Comments here refer to internal documentation, which is comprised of comments that developers write within the source code.

• Provide Summary before every Class, Delegate, Interface. This can be written by “///” . Summary includes:a. Author’s nameb. Description.c. Known Bugs and/or side effects.

• Write a Short description ( a comment ) before every method mentioning about the functionality of the method and also mention about Global Variables modified.

Comments Contd…• If you have to write some complex logic,

document it very well with sufficient comments.• When modifying code (bug

fixing/revision/maintenance), always keep the commenting around it up to date. Add an additional comment giving details of who made the change, the date the change was made and an Issue tracking number if available. The format would be as follows // <Name>, <Date – DD MMMMM YYYY format>, <Issue>//// Changes starts here

Code………….// Changes end here <Name>

• Avoid clutter comments, such as an entire line of asterisks. Instead, use white space to separate comments from code.

• Use complete sentences when writing comments. Comments should clarify the code, not add ambiguity.

• Comment as you code because you will not likely have time to do it later. Also, should you get a chance to revisit code you have written, that which is obvious today probably will not be obvious six weeks from now.

• Use comments to explain the intent of the code. They should not serve as inline translations of the code.

• Comment anything that is not readily obvious in the code.

Comments Contd…• Use comments on code that consists of

loops and logic branches. These are key areas that will assist source code readers.

• Throughout the application, construct comments using a uniform style with consistent punctuation and structure.

5. Exceptional Handling:• Use the structured error handling (Try, Catch, Finally and

Throw). Try// statements that need to be execute go hereCatch

// code to handle the exception go here. You// would typically write clean to take corrective// action for the exception raised

Finally// code that needs to execute irrespective of the

exception// occurrence would go here. You would typically

write// clean up code here

Exceptional handling contd…• Write down your custom Exceptions if

possible derived from base class System.Exception.

• Always close the connection in Connected Architecture in Finally Statement.

Miscellaneous ( Useful Tips ): • Use #region to group related pieces of group

together. If you see proper grouping using #region, the page should be like this when all definitions are collapsed.

• Use Tabs for Indentation. Do not use Spaces.• To concatenate strings use StringBuilder class

instead of ‘+’ to improve performance.• Method should not have more than 5

arguments. Use structures for passing multiple arguments.

• Avoid long methods. Define some limit(e.g. 200 lines) if method goes beyond the limit then it’s time to refactor it!

• Do not make the member variables public or protected. Keep them private and expose public/protected Properties.

Documentation:Following documents should be made for

every Project:1. DLD ( Detailed level Design ):

# Class Design Specification of every Class in their respective Layer.2. HLD ( High level Design ):

# System Architecture must be defined.3. Database_Design_Dcument:

# Table files or Entities and Volatility of every table must be mentioned.4. Defect Tracker.

Thank you-

The important thing is not to stop questioning. - Albert Einstein

Q and A