Home
Comments - Do you comment each property and method?
  v7.0 Posted at 2/08/2018 4:48 PM by Partho P. Das

​​​It's important that you have a consistent code comment standard throughout an application, regardless of language. Therefore, other developers can quickly determine the workings of a function/sub/class/stored procedure. Ideally, the code should be as simple and self-explanatory as possible.

UPDATE: See Robert Martin Chapter 4: Comments  Clean Code: A Handbook of Agile Software Craftsmanship

E.g. catch (InteropServices.COMException ex) //Catch all COM Exceptions from third-party COM component

In JavaScript and HTML, you should put these comments between the 
<HEAD> and </HEAD>
tags. 

To delimit the comments (ie top and bottom), you should use the standard block comment markers of 
<!-- and -->. 

A CSS file should be delimited with the block comment marks of ​​
/* and */.

If the file contains any function/sub module/class declaration, comments will be contained​​ to each of them containing at least the following:

  • function/sub module/class name
  • role of the function/sub module/class declaration

Above a method or property declaration:

/// <summary>
/// 
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
/// <remarks ></remarks>

​Bonus - you can automatically generate documentation - but the number of clients that want this is minimal.


Related rules

    Do you feel this rule needs an update?

    If you want to be notified when this rule is updated, please enter your email address:

    Comments:

    Note: Social Media login for Yotpo is not working in IE or Safari, please use Chrome. We are waiting for Yotpo to fix it.