- Code Documentation is Pitiful
- Lots of Public variables
- Poor class planning
Next I want to move my variables from the access level of public to protected. This means that only objects that are derived from this class can see these variable, everyone who just uses an instance of the class has to get at them through either a method or a property (or not at all).
So for all the variables that need to be viewed outside the class (location, rotation, etc) I am creating a public Property.
Then to top things off, I am adding XML style comments to all my class members. Visual C# has a great shortcut for doing comments, on the line before a class or class member, type /// and it will prefill a template for a XML style comment.
for example, the code
public void SetPosition(Vector2 point)
{
this.position = point;
}
on the line before it, I typed in /// and got
/// <summary>
///
/// </summary>
/// <param name="point"></param>
public void SetPosition(Vector2 point)
{
this.position = point;
}
now I can just fill in my description and the decription for the point parameter. That makes life a little easier. Visual C# also uses XML comments in tooltips when you access that class member in some other area of your code.
You may have also noticed that I moved GameObject out of the class of the current game and put it in my own namespace johnnyGizmo. So when I want to use it in a new game, I just need to add a class from the solution explorer and in my file say
using johnnyGizmo;
Later when I am happy with how the class looks, i.e. it is finished, I can compile it to it's own library for simple use in other programs. You can see the refectored GameObject files Here
4 comments:
Maybe it's just me, but the /// comments are completely useless and I always end up ripping them out of code so I don't need to look at them. If the function and params aren't clearly named as to identify them they need to be renamed.
I think they can be very useful when they are populating tooltips. I do wish they were a little more condensed as they take up a lot of coding space. I do wish I would err on the side of more documentation than less, cause usually I'm lucky if I remember to document at all!
If you're using VS2005 (2008?) you should check out GhostDoc. Its pretty keen and helps auto-document your methods. It names them too! (No I don't work for them, but I love it for making my documentation a breeze!)
http://www.roland-weigelt.de/ghostdoc/
Your using C# you say?
Why not use actual properties like this:
public Vector2 Position
{
set
{
this.position = value;
}
}
Post a Comment