Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

Re^2: The sourcecode *is* the documentation, isn't it?

by deprecated (Priest)
on Aug 13, 2007 at 17:04 UTC ( #632270=note: print w/ replies, xml ) Need Help??


in reply to Re: The sourcecode *is* the documentation, isn't it?
in thread The sourcecode *is* the documentation, isn't it?

I cannot comprehend how anyone could say that any form of documentation (save that which is incorrect or absent) is "... rude ..." Even private functions should be documented. An example from an API I wrote a while ago (for a largeish company, but not on CPAN, sorry) included documentation for all the private functions because otherwise it was unclear what they did. In this example, the API served to perform exotic math on matrices. One couldn't use simple operators because the operators didn't operate in the exotic way the API required. So private, "behind-the-scenes" functions were made to perform these operations (I suppose we could use some of the newer perl functions with respect to overloading or defining our own operators, but this was a while ago, and those new techniques would still have to be documented).

So let's say there were functions like _alex_weird_add() and _alex_weird_multiply(). Definitely private functions because they performed tasks that weren't "add" or "multiply." I didn't want the user using them, I didn't want them exposed to the rest of the API, but I needed to make sure that somebody down the line (there is always churn in software shops) would be able to read my POD (and in this case my Params::Validate clauses too) and be enlightened.

To suggest that not having the documentation somehow makes the reader of the code ... less in the dark just seems entirely to miss the point of documentation.

--
Tilly is my hero.


Comment on Re^2: The sourcecode *is* the documentation, isn't it?
Re^3: The sourcecode *is* the documentation, isn't it?
by dragonchild (Archbishop) on Sep 11, 2007 at 01:31 UTC
    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:
    1. Does it work?
    2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (14)
As of 2014-08-22 11:13 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (156 votes), past polls