[thelist] Free tips (bit long, sorry)

[Jon Haworth]

<tip type="tips">

A post that starts out as a rant about how not to do something can be
turned into a tip about how to do it correctly or more effectively.

</tip>



<tip type="comments" audience="whoever did the code I'm working on">

These are useless comments.

' Open an ADO connection using the global connection string
adoConnection.Open strGlobalADOConnectionString

' Set up the ADO command and execute it
adoCommand.CommandText = "spAuthenticateUser"
adoCommand.CommandType = adCmdStoredProc
Set rsAuthenticateUser = adoCommand.Execute

As you can see, [name deleted because I'm in a good mood] was sensible
enough to name their variables well, and in doing this they've made the
code "self-commenting". The comments they've added are redundant and only
make the code harder to maintain.

What's wrong with them? As someone working with this, there are two things
I need to know to understand it: the intent, and the method used to
accomplish the intent. The comments should show the intent. The code should
show the method. In the example above, both are showing the method. This is
confusing. I am displeased. I would like to hunt down [programmer who shall
not be named] and express my feelings through the medium of a 2-by-4.

That was from the authentication section of a VB program. If I'd done it
originally I would probably have put something like this at the top of the
whole section, then put the relevant code underneath.

' In this section we're going to authenticate the user.
' This involves sending their username and a hash
' of the password to the spAuthenticateUser stored
' procedure. This returns a value in a field called "UserID":
' if this value is 0, there wasn't a match, so we exit the
' program; if it's greater than 0, there was a match,
' and this value is the primary key of the Users table for
' the row that matched. We'll use this value as their
' user ID throughout the program.

When I'd reached the next logical block of code, I'd have inserted a few
blank lines and done another comment to show the intent of the next bit:

' If we haven't exited yet, we know the user is
' authenticated, and we have their user ID.
' We can now go ahead and grab their preferences from
' the spGetUserPreferences stored procedure.

OK, the odd redundant comment is handy now and again: I'm always doing
things like

' Finished with prbProgressBar
End With

to save hammering down on PageUp just to find out what the With block is
using, and that's fine, but if you don't include comments showing the
INTENT of your code, you're only going to annoy anyone who has to look at
it in the future (including yourself).

</tip>


Cheers
Jon