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