Geeks With Blogs

News Google

Nick Harrison Blog<Nick>.Next()


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?

Posted on Monday, September 22, 2008 6:43 PM | Back to top


Comments on this post: What Can We Do For Meaningful Variable Names?

# re: What Can We Do For Meaningful Variable Names?
Requesting Gravatar...
Numbered method names... yikes.

I have found GhostDoc's usefulness markedly decreases as code is refactored. Who takes the time to go back and re-initialize the triple-slash comments after moving, renaming, and consolidating methods?

Maybe I am too lazy by letting my naming and Intellisense do the work for me. I can see when producing a framework to other developers it would be useful along with tech writers and tech reviewers, yada, yada.

rusty
Left by rusty on Sep 23, 2008 10:55 AM

comments powered by Disqus

Copyright © Nick Harrison | Powered by: GeeksWithBlogs.net