Sunday, May 2, 2010

How to: Use comments with intellisense

Now I am not much of a comment user but there are some times when comments are very helpful and since I am going to start adding comments in my tutorials I thought I would briefly explain how to use them before hand.

One reason I use comments is to signify that something will be changing. The reason I do this is so that in case I forget to change it when I look back on the code I can remember. Now this isn't the best way to use comments as it doesn't really help the readability of your code or your coding efficiency.

The next reason I comment stuff is for things that I may find confusing if I were to look at it in a month. Things such as variables that are sort of complicated, code blocks with a lot of math or random things that look like they don't belong. Other things may include brief explanations for the designer who will be changing that specific variable or group of variables.
This is a code snippet from my screen manager class which is part of my menu system. The comment is reminding me of how we create a new content manager for each screen because when you unload each screen you just unload each content manager. If you want to read more about loading and unloading you can read Shawn Hargreaves blog post about it here.

Now another reason I use comments is for summaries, either variable summaries or function summaries, these are very good when combined with variable names that explain what they are, or if you like those read variable names you can also make variable summaries as a part of your function summaries. To create a summary go right above the variable or function you want to summarize and type in 3 forward slashes '/' and it will auto create a summary template for you that will look like this.
Usually I will ignore the part about returns and if my variable names and types are simple ignore the parameters but adding in some info is never bad. Our New Particle Function will now look like this. Now you may think this is a bit excessive for comments, well it is, but you can use these summaries in very good ways.
The first way is when your writing your code and IntelliSense pops up and you highlight your function that you summarized it will now show the summary under its variable definition like so.
Next when you highlight the function after you have already written it, lets say you forgot what the function did it will show the summary there as well.
Lastly if you start to write the parameters it will show the parameter summaries like this.
I hope you find this explanation of comments helpful as it has helped me a lot and will continue to help especially for complicated code that you have not written. So if you are going to share your code be sure to comment it well enough for other people to use it.

No comments:

Post a Comment