Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

Re: flower box comments

by bluto (Curate)
on Nov 17, 2003 at 18:36 UTC ( #307779=note: print w/replies, xml ) Need Help??


in reply to flower box comments

The main things I like about these types of comments are that they allow the reader to determine ...

- Assumptions that the routine makes (e.g. a resource is locked by the caller before the routine is called; the routine isn't called very often so performance is not important and the implementation is simplified). Obviosly, you'll want to put in assertion-like sanity checks to handle these whenever you can, but there are cases where this is not possible and these may be buried (hence obfuscated) in the code.

- Limitations of the implementation and future changes that could be made. Many times this is something like an idea of how to improve performance (i.e. by introducing some complexity) if an assumption changes about how the routine will be used in the future.

Unfortunately, some project management types who believe that "more == better" get real pedantic and start mandating that all sorts of useless drivel appear here that is either quickly outdated and/or can be gleaned from the first two lines of the sub.

bluto

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://307779]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others imbibing at the Monastery: (5)
As of 2019-10-19 16:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?