If they are scripts, I would +1 if the comments include examples of standard ways one would expect to call the script (command lines and sample output). This is
really helpful in picking up a script.
I can put my money where my mouth is. I have uploaded a couple of script to the Code Catacombs which do just that. I won't link to them directly, but search for pinger and nugid for a couple of examples.
<update date="2001-11-26"> Here's a thing that is a definite no-no worth a -1: "gratuitous use of & when calling a subroutine" (e.g. &func($x,$y)) except if @_ is to be passed to the called routine... which is hardly ever the case. I find this to be pretty cargo-cultish, not to mention noisy.</update>
--g r i n d e r
