P is for Practical | |
PerlMonks |
Re^3: The sourcecode *is* the documentation, isn't it?by dragonchild (Archbishop) |
on Sep 11, 2007 at 01:31 UTC ( [id://638199]=note: print w/replies, xml ) | Need Help?? |
Yay. You completely missed the point of what I was saying. Let me rephrase.
Private functions should be documented in the code. They should NOT be documented in the PUBLIC contract. So, in your code of _alex_weird_add(), those functions should be documented (quite heavily, I'd imagine) in a set of comments at the beginning of the source file, at the function, and where those private functions are called. In other words, only those things that are supposed to be used by the user should be documented in the place the user goes to find out how your widget works. ANYTHING ELSE IS JUST CONFUSING. Being confusing is rude. Hence, why I said what I said. My criteria for good software:
In Section
Meditations
|
|