Comments - Do you comment each property and method?
Updated by Brady Stroud [SSW] 6 months ago. See history
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.
Categories
Acknowledgements
Need help?
SSW Consulting has over 30 years of experience developing awesome software solutions.