Tuesday, April 11, 2006

Comments are for 'why?'

I have blogged on this before, but I keep running across it, so here goes again...

Here is a snippet from some VB code I am having to clean up at the moment.

    Public Property PasswordKeyboard() As Boolean
'Retrieves PasswordKeyboard
Get
Return boolPasswordKeyboard
End Get
'Assigns to PasswordKeyboard
Set(ByVal Value As Boolean)
boolPasswordKeyboard = Value
End Set
End Property


Check out the comments! Your code should clearly explain to the reader your understanding of the problem domain, and your solution to the problems involved. Your code should answer a few questions: What is it doing? How is it doing it? and Why is it being done that way?
'What' should be covered by the method and class names.
'How' is covered by the method body (which should be made easy to read)
'Why' is something you can't easly enbed in the code. This is where comments are invaluable. This is what comments are for.

The only reason I can see for having the comments in the above code is to explain why you put the following lines of code in the file. This only make sence if you are trying to document/teach the VB
language. Maybe this is why this problem is so prolific. When someone learns to program they come across this sort of commenting all the time in tutorials. Students duplicate what they are fed, so they add the same comments to their own code.

Do me a favor... if you see this style of commenting anywhere in code you have your hands on, just delete it. The code will be MORE readable, and smaller. Your brain will thank you.


No comments:

GitHub Projects