|Keep It Simple, Stupid|
Re: flower box commentsby adrianh (Chancellor)
|on Nov 17, 2003 at 15:01 UTC||Need Help??|
I have my doubts about this style too :-)
First off, as several other people have pointed out, if this is documentation aimed at the users of the code then POD would be the preferred format. That way you get the support of a lot of POD:: modules for formatting and reading your documentation.
Second, look at what the comments tell you - or rather what they don't:
The function name and the filename it lives in. Both of which we already know (we're looking at the file to see the comment, and the subroutine name is part of the subroutines declaration.)
The arguments are a database handle (to what?) and an SQL query string (of what format?). This gives us no more information that we would get from the first line of the function:
It would be even easier if we called the database handle $dbh which would be familiar to all users of DBI, and a more descriptive name for the sql query.
Tells us, I think, that we get an array of the rows returned by the SQL query. This is:
All of this information is better expressed in the code itself. Rather than spending time writing comments that can easily get out of sync with the code, spend time writing clear expressive code. If you can't look at a subroutine and understand what it does rewrite it until you do. Break it into smaller subroutines, use better subroutine names, use better variable names, etc.
For example the original routine might be better expressed as (guessing it's actual use since the comment doesn't actually say :-)