O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

Commenting Best Practices

1.340 visualizações

Publicada em

Importance and art of commenting of software development.

  • Entre para ver os comentários

  • Seja a primeira pessoa a gostar disto

Commenting Best Practices

  1. 1. Commenting The Jaxara IT Ltd. Mahmudul Haque Azad
  2. 2. Why commenting <ul><li>Coding is for clients and commenting is for developers. </li></ul><ul><li>Commenting helps you and your co-developer as well. </li></ul><ul><li>Let your code talk to you using “commenting” as language. </li></ul>
  3. 3. 8 tips for commenting <ul><li>1. Comment each level </li></ul><ul><li>Comment each code block, using a uniform approach for each level. For example: </li></ul><ul><li>For each class, include a brief description, author and date of last modification </li></ul><ul><li>For each method, include a description of its purpose, functions, parameters and results </li></ul><ul><li>2. Use paragraph comments </li></ul><ul><li>Break code blocks into multiple “paragraphs” that each perform a single task, then add a comment at the beginning of each block to instruct the reader on what is about to happen. </li></ul><ul><li>/// Check that all data records </li></ul><ul><li>/// are correct </li></ul><ul><li>foreach (Record record in records) </li></ul><ul><li>{ </li></ul><ul><li>if (rec.checkStatus()==Status.OK) </li></ul><ul><li>{ </li></ul><ul><li>. . . </li></ul><ul><li>} </li></ul><ul><li>} </li></ul><ul><li>/// Now we begin to perform </li></ul><ul><li>/// transactions </li></ul><ul><li>Context ctx = new ApplicationContext(); </li></ul><ul><li>ctx.BeginTransaction(); </li></ul><ul><li>. . . </li></ul>
  4. 4. 8 tips for commenting (cont.) <ul><li>3. Align comments in consecutive lines </li></ul><ul><li>For multiple lines of code with trailing comments, align the comments so they will be easy to read. </li></ul><ul><li>const MAX_ITEMS = 10; // maximum number of packets </li></ul><ul><li>const MASK = 0x1F; // mask bit TCP </li></ul><ul><li>4. Don’t insult the reader’s intelligence </li></ul><ul><li>Avoid obvious comments such as: </li></ul><ul><ul><li>if (a == 5) // if a equals 5 </li></ul></ul><ul><ul><li>counter = 0; // set the counter to zero </li></ul></ul><ul><li>This wastes your time writing needless comments and distracts the reader with details that can be easily deduced from the code . </li></ul><ul><li>5. Be polite </li></ul><ul><li>Avoid rude comments like, “Notice the stupid user has entered a negative number,” or “This fixes the side effect produced by the pathetically inept implementation of the initial developer.” Such comments do not reflect well upon their author, and you never know who may read these comments in the future: your boss, a customer, or the pathetically inept developer you just insulted. </li></ul>
  5. 5. 8 tips for commenting (cont.) <ul><li>6. Comment code while writing it </li></ul><ul><li>Add comments while you write code and it’s fresh in your memory. If you leave comments until the end, it will take you twice as long, if you do it at all. “I have no time to comment,” “I’m in a hurry,” and “The project is delayed” are all simply excuses to avoid documenting your code. Some developers believe you should write comments before code as a way to plan out your ultimate solution. For example: </li></ul><ul><ul><li>public void ProcessOrder() </li></ul></ul><ul><ul><li>{ </li></ul></ul><ul><ul><li>/// Make sure the products are available </li></ul></ul><ul><ul><li>/// Check that the customer is valid </li></ul></ul><ul><ul><li>/// Send the order to the store </li></ul></ul><ul><ul><li>/// Generate bill </li></ul></ul><ul><ul><li>} </li></ul></ul><ul><li>7. Update comments when you update the code </li></ul><ul><li>There is no point in commenting correctly on code if the comments are not changed with the code. Both code and comments must move in parallel, otherwise the comments will actually make life more difficult for developers who maintain your code. Pay special attention to refactoring tools that automatically update code but leave comments unchanged and hence obsolete in the same instant. </li></ul>
  6. 6. 8 tips for commenting (cont.) <ul><li>8. The golden rule of comments: readable code </li></ul><ul><li>One of the basic principles for many developers: Let your code speak for itself. Although one suspects this movement is led by programmers who do not like to write comments, it is true that self-explanatory code can go a long way toward making code that’s easier to understand and can even render comments unnecessary. Following code shows how clear self-explanatory code can be: </li></ul><ul><ul><li>Calculator calc = new Calculator (); </li></ul></ul><ul><ul><li>calc.Set(0); </li></ul></ul><ul><ul><li>calc.Add(10); </li></ul></ul><ul><ul><li>calc.Multiply(2); </li></ul></ul><ul><ul><li>calc.Subtract(4); </li></ul></ul><ul><ul><li>Console .WriteLine( “Result: {0}”, calc.Get() ); </li></ul></ul>
  7. 7. Some conventions <ul><li>Use triple front slash /// while commenting in the body of *.cs /*.js code. </li></ul><ul><li>Use <!-- --> while commenting in *.html/*.aspx/*.xml/*.xslt </li></ul>/// Getting the requested URL string url = HttpContext.Current.Request.Url.ToString();
  8. 8. Some conventions (cont.) <ul><li>Use -- to comment in *.sql </li></ul><ul><li>Use /*… */ to comment in *.css </li></ul>
  9. 9. Commenting in Module Header Module Header commenting template
  10. 10. Commenting in Module Header(cont.) <ul><li>An example </li></ul>
  11. 11. Class level commenting.
  12. 12. Routine/function/method level commenting. <ul><li>Here commenting in the header is a MUST. </li></ul><ul><li>Commenting in the body is optional. But for readability we should do commenting as much as possible. </li></ul><ul><li>Any complex logic should be commented. </li></ul>
  13. 13. Routine/function/method level commenting (cont.) <ul><li>Comments in the header should have one summary section and a short description for all the parameters and return value. </li></ul>
  14. 14. Routine/function/method level commenting (cont.)
  15. 15. Commenting for Properties <ul><li>In .net we use properties for various purpose. Following commenting should be used for comments for property. </li></ul>
  16. 16. That’s all…. <ul><li>Now you are aware of Jaxara standard of commenting. Now lets explore some commenting example of different code modules. </li></ul>
  17. 17. JavaScript commenting
  18. 18. XSLT commenting
  19. 19. CSS commenting
  20. 20. SQL Commenting
  21. 21. <ul><li>Thank You </li></ul>