Comments - Do you comment each property and method?
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
<HEAD> and </HEAD>
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:
/// <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.
Do you feel this rule needs an update?