Write documentation comments on every method, every member. This is the sixth in a series of posts on Code Gardening - the practice of making small
improvements as you see them while you are working.
Well written documentation comments make it easier to understand the intent of the code that you’ve written. This will assist any developer who comes along after you - which might just be you, in six months time.
Consider this fragment of code from an earlier post:
This routine isn’t difficult to understand, but taking the time to do so would slow you down - and you only have that luxury if you’re reading the definition, not at the point of consumption.
Adding a good documentation comment to this method makes the method easier to understand:
With this comment in place, Visual Studio Intellisense lights up with useful information about the method as it is used:
You can see how intellisense is showing information that you normally would need to read the implementation to learn. It’s also including information that isn’t immediately discernable from the code, like the fact the search is case insensitive.
The usefulness of these comments isn’t limited to intellisense, however - documentation generators like
SharpDox will include the documentation in the generated website.