in reply to Re: Are there any drawbacks to comments -- can they hurt the performance of Perl code?
in thread Are there any drawbacks to comments -- can they hurt the performance of Perl code?
Nothing beats clear and elegant organization and good names for functions and variables. Some people are skilled at that and naturally remember to do it. Some aren't and don't. Mandated function comments serve to help the latter. They are a reminder to think about how to communicate, rather than just how to do get the computer to do the job at hand. If the clarity of GrandGather's code here at PM is any indication, he probably doesn't need that. I need the extra step. Often I end up with no function comment, but I've changed the name of the function to something more informative. It's nice when what one needs to know at a glance fits well in the function name. When it doesn't, a function comment is a great help.
Function comments can also provide an outline structure, like section headings in a book. When I'm going back to find something in "Perl Best Practices", I can find it more easily because there's a brief rule summary right below the section title. I don't have to read the whole section and the supporting arguments to be reminded what the rule is. Similarly, in
The comment helps me see what's done here, without reading the part where I set permissions on the new, updated monthly-total file, having renamed the previous file as a backup. Writing the comment may also prompt me to move writing of monthly totals somewhere else, or leave a TODO for a time when such a change can be adequately tested.# Accumulate and print YTD total, recording updates to disk. sub PrintYTD { ... }
So for me, comments make for better code, both as a prompt for thinking about how the code communicates to people, rather than the compiler, and as an outline structure.
|
|---|
| Replies are listed 'Best First'. | |
|---|---|
|
Re^3: Are there any drawbacks to comments -- can they hurt the performance of Perl code?
by leocharre (Priest) on Aug 14, 2006 at 13:58 UTC |