Presentation on software documentation and coding standards


Published on

Presentation on software documentation and coding standards

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • In long term, ROI, Performance and efficiency comes below reliability and Maintainability, spend more on resolving issues, trying to understand the problem throughout the life of your application.
  • Presentation on software documentation and coding standards

    1. 1. Presentation on Software Documentation and Coding Standards By Chirag Singhal
    2. 2. Concept: Efficient yes, But Reliable and Maintainable first !
    3. 3. Purpose of Coding Standards anddocumentation :• 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.
    4. 4. How to follow Standards across theteam !• 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.
    5. 5. Presentation categorized into two parts:1. Coding Standards.2. Documentation.
    6. 6. 1. Naming StandardsPascal 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.
    7. 7. 1.1 Assembly, File Names andNamespaces• 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.
    8. 8. 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.
    9. 9. 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}
    10. 10. 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 classs 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
    11. 11. 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.
    12. 12. 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.
    13. 13. 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.
    14. 14. 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;
    15. 15. 3.6 Variable NamesUse 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.
    16. 16. 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;
    17. 17. 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 name b. 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.
    18. 18. 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>
    19. 19. • 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.
    20. 20. 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.
    21. 21. 5. Exceptional Handling:• Use the structured error handling (Try, Catch, Finally and Throw). Try// statements that need to be execute go here Catch // 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
    22. 22. 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.
    23. 23. 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!
    24. 24. • Do not make the member variables public or protected. Keep them private and expose public/protected Properties.
    25. 25. 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.
    26. 26. Thank you- The important thing is not to stop questioning. - Albert Einstein Q and A