What can we do for meaningful variable names?
You hear much about naming conventions and some shops still have some arcane rules in place. Fortunately most of us have stepped beyond Hungarian notation. I have seen some shops define rules that the method name should include the number of parameters. I have seen shops define rules that would ban overloading and insist on a sequence number for methods that should be overloads. I have seen shops that wanted the Requirement Number embedded in method names, and I have seen shops put maximum character size limits to simplify reading. This unfortunately led to awkward abbreviations.
None of these standards have led to more meaning variable names. The fact that a variable is an integer or a string does nothing for me. Having a method signature come like:
Public void int DoSomething (string strParam, int intParam)
does nothing for us. Having one like:
Public void int ProcessIncomingClaims (string branchCode, int transactionID)
Can be very enlightening.
Like legislating morality, none of these rules will guarantee that the names are good. At the same time, almost any set of “good” rules could still be applied and end up with “bad” variable names. We may not always know when a name is “good” but we usually know when the name is “bad”.
Enter GhostDoc. GhostDoc is a wonderful tool designed to help automate your comments. Caution it works best for C#, but they are building support for VB. The intention here is that GhostDoc takes your method, properties, parameters, etc. and splits them to come up with the documentation for that item. There are several thinks that seem to be happening here. First it splits the words at a case change. Second, it interprets methods as being in the form verb – object and will attempt to structure the comment like that.
For instance, if you have a method called DataBind (), GhostDoc will come up with the comment:
/// <summary>
/// Datas the bind.
/// </summary>
This is clearly not what we want for a comment. Note that the naming convention was not followed. We would want to have methods following the pattern of Vern Object. Here it is following the convention of Object Verb. Ghost Doc ends up with a comment that does not make sense grammatically. Now consider the comment generated for the method BindData ():
/// <summary>
/// Binds the data.
/// </summary>
Our method name follows the naming conventions that we have setup and now the generated comment makes sense as well.
Try it and you will find that whenever GhostDoc does not come up with a boiler plate comment, your variable names or method names or property names are probably not named well.
Not a bad litmus test for good names!
Just like Ghost Writers in the publishing world, there is only so much that GhostDoc can do. It does a good job of structuring your comments. It does a good job of mapping out the details needed for comprehensive XML documentation. It also does a good job brining in ancestor details when overriding from a base class.
It does not explain how logic works or why logic is needed. This you still need to add yourself, but at least you will know where it goes to produce in comprehensive documentation. The better you name your methods and parameters, the less you should have to write. The more highly cohesive your methods, the less you should have to write. The less you have have to write manually, the better your code can be understand without your comments.
Has anyone else used GhostDoc to help ensure naming conventions or help ensure that code is readable?
?
You hear much about naming conventions and some shops still have some arcane rules in place. Fortunately most of us have stepped beyond Hungarian notation. I have seen some shops define rules that the method name should include the number of parameters. I have seen shops define rules that would ban overloading and insist on a sequence number for methods that should be overloads. I have seen shops that wanted the Requirement Number embedded in method names, and I have seen shops put maximum character size limits to simplify reading. This unfortunately led to awkward abbreviations.
None of these standards have led to more meaning variable names. The fact that a variable is an integer or a string does nothing for me. Having a method signature come like:
Public void int DoSomething (string strParam, int intParam)
does nothing for us. Having one like:
Public void int ProcessIncomingClaims (string branchCode, int transactionID)
Can be very enlightening.
Like legislating morality, none of these rules will guarantee that the names are good. At the same time, almost any set of “good” rules could still be applied and end up with “bad” variable names. We may not always know when a name is “good” but we usually know when the name is “bad”.
Enter GhostDoc. GhostDoc is a wonderful tool designed to help automate your comments. Caution it works best for C#, but they are building support for VB. The intention here is that GhostDoc takes your method, properties, parameters, etc. and splits them to come up with the documentation for that item. There are several thinks that seem to be happening here. First it splits the words at a case change. Second, it interprets methods as being in the form verb – object and will attempt to structure the comment like that.
For instance, if you have a method called DataBind (), GhostDoc will come up with the comment:
/// <summary>
/// Datas the bind.
/// </summary>
This is clearly not what we want for a comment. Note that the naming convention was not followed. We would want to have methods following the pattern of Vern Object. Here it is following the convention of Object Verb. Ghost Doc ends up with a comment that does not make sense grammatically. Now consider the comment generated for the method BindData ():
/// <summary>
/// Binds the data.
/// </summary>
Our method name follows the naming conventions that we have setup and now the generated comment makes sense as well.
Try it and you will find that whenever GhostDoc does not come up with a boiler plate comment, your variable names or method names or property names are probably not named well.
Not a bad litmus test for good names!
Just like Ghost Writers in the publishing world, there is only so much that GhostDoc can do. It does a good job of structuring your comments. It does a good job of mapping out the details needed for comprehensive XML documentation. It also does a good job brining in ancestor details when overriding from a base class.
It does not explain how logic works or why logic is needed. This you still need to add yourself, but at least you will know where it goes to produce in comprehensive documentation. The better you name your methods and parameters, the less you should have to write. The more highly cohesive your methods, the less you should have to write. The less you have have to write manually, the better your code can be understand without your comments.
Has anyone else used GhostDoc to help ensure naming conventions or help ensure that code is readable?