Ever had that WTF?! experience while opening a classfile as developer? Let's have one right now:
Okay, maybe not a good example because you might actually know what the use of a Location is, having a name and a radius (on the globe?) but without meaningfull comments we can only GUESS, can't we? At least, the developer who wrote the class in the first place has us guessing. Yes, guessing. Why? Because there are no comments in the class. Somebody tried to add a comment but got stuck at adding the summary..
Can code comments be done any better?
This looks pretty nice, altough it might be a little overdone. At least the class and all methods have comments that actually tell me something, which I personally think is pretty nice.
In the codebase we are currently working on we got the same feeling when going over alot of classes. So we decided to do something about it!. And we introduced a weekly scheduled! half our of adding comments to code.
However, that weekly scheduled job of adding comments to code unfortunately turned out to become a feast to add dummy comments, just to get down the number of XML compiler warnings spawned by visual studio. Some of the developers took on the weekly job by installing GhostDoc and press Ctrl-Shift-D on all public methods and properties of classes that did not have comments yet.
So what am I getting at? Do I want those comments in code or not? Sure I do! But when we start commenting the code, we have to understand to only do so if we really want to give meaningfull comments.
Adding meaningfull comments means that you also have to start -reading- the code. And than sometimes you might have questions about the code and that is why you also might need some more time like discussing the code over with the developer who last changed that piece of code at some point. Including having a look at the SVN-history of the particular class you are commenting and see what kind of changes were made, and why…
In all, it means that we are not only pressing the GhostDoc Ctrl-Shift-D shortcut for automatic comments (which usually do not mean anything and are not helpfull) but we could also add comment that contain "questions".
An example of a meaningfull comment for a property: "Enum exposes the type of this instance. Looks like this property can be removed?"
If you start commenting code please do not "just comment" but also think about why/what to comment. If we do not think about the comments, the exercise of adding them is completely useless. Adding comments is NOT about the compiler warning-counter that we as team want to reduce. Commenting code is about adding knowledge. Adding your thoughts and questions about the code. Adding suggestions for future refactoring.
So don't be afraid to add comments to code! Adding questions as comments is valuable. Much better than adding no comments at all in the first place.