Comments - Do you comment each property and method?

Last updated by Brook Jeynes [SSW] 7 months ago.See history

This rule has been archived
Archived Reason: out of date

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.

We open source. Powered by GitHub