in reply to Suggestions for a new module

croak "WTF? You gave me a nested array for the type of '$name'?!?" ... croak "Can't grok type specifier '$type' for member '$name'";

Please, please, please do not be glib or flippant or obscure when you're phrasing diagnostic messages. Diagnostic messages are where you should put on your best interpersonal and technical communication skills.

(The best diagnostics say what the program was trying to do, where in the code it was trying to do it, what the program got, and what the program was expecting. That's all.)

To a lesser degree, comments in the code should also be informative without being too informal. Your code is a mode of your personal expression, and a few well-placed mutterings about your thoughts may guide the reader, but if the tone sounds too informal, it can get in the way of a useful code review or bug hunt.

This is a personal preference, but one which is tempered by having to work with source code from many authors over a long career with many people with different personalities and from many different cultures.

--
[ e d @ h a l l e y . c c ]

Replies are listed 'Best First'.
Re: Re: Suggestions for a new module
by Stevie-O (Friar) on Apr 16, 2004 at 05:17 UTC
    Ahh, thanks for reminding me. I had fully intended to clean up the majority of the comments (the entirety of the POD was crafted by hand, the module was not templated), but I'd forgotten about the error messages.
    --Stevie-O
    $"=$,,$_=q>|\p4<6 8p<M/_|<('=> .q>.<4-KI<l|2$<6%s!<qn#F<>;$, .=pack'N*',"@{[unpack'C*',$_] }"for split/</;$_=$,,y[A-Z a-z] {}cd;print lc