Today I want to focus on coding in Dot Net as it pertains to comments. Folks responded to yesterday’s editorial with a position that comments are essential for them. I agree, and want to break out different kinds of comments I like to use in Dot Net Code.
First there is the ability for you to define the purpose of a method and the properties used as inputs to a method, when you define a class. This is done with a form of comment that is converted. You’re see the results of it when you work in visual studio. It provides inteli-sense feedback when you call a method commented in this fashion. If you overload a method, then multiple options appear in the intellisense dialog. The better you define your methods, the more useful it is when you forget how things are supposed to work.
I believe this method mimics the Java Doc techniques for writing Java code. For this reason, you can also generate a form of documentation for your classes.
Another form of comments I like to use is when there is a process that is being implemented in code that is not readily apparent. Timely comments telling the developer what is going on, or what precedence is needed are valuable.
Another form of comments may be found in your naming conventions. While I don’t like putting the data type into the name of a variable, using a singular or plural name can separate enumerable objects from scalar ones.
Here’s a simple commenting technique: Make your method names meaningful. I would prefer a long, meaningful, method name without comments over a short method name with lots of comments. With intelliSense, auto completion makes long method names more practical. Method names show wherever they are used, so that the purpose is exposed without having to refer to comments in the source object.
To be clear, I am not saying a comment is bad thing, even if it is inline or a group. What I am saying is that comments should be used when other techniques do not provide the necessary degree of clarity.
I prefer not to use comments for things that are managed by external sources. For example, I don’t put version control information (who did what when and why) in a header comment for code. My version control system makes that information available to me, and a diff compare of different versions tell me much more than I have time to put into comments.
Maybe we’ll talk about comments in SQL Code next time. I do a LOT more commenting there because you have limits due to the nature of the language. Maybe you have suggestions you’d like to share on Dot Net, SQL or any other code tool where comments are useful. You can share your thoughts in comments here or by email to btaylor@sswug.org.
Cheers,
Ben