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

This is a straw man. Code, comments, and documentation are documents meant for different audiences. Code is meant for the computer first and the developer second. Comments are meant to clarify for the developer when code is difficult to read. Documentation is meant for the user. I find it very ... rude ... when a developer documents private functions. I don't want to know them! I want to know the interface I'm meant to use. If I want to contribute back to your product, I will read the code and the comments. That's when I'll find the private functions and funky variables. If a piece of code violates accepted norms, then it should be commented. If it does something really wonky, it should be commented. Otherwise, you shouldn't say anything at all. Too many comments are often worse than none at all.

------
We are the carpenters and bricklayers of the Information Age.

Then there are Damian modules.... *sigh* ... that's not about being less-lazy -- that's about being on some really good drugs -- you know, there is no spoon. - flyingmoose

I shouldn't have to say this, but any code, unless otherwise stated, is untested

Comment on Re: The sourcecode is the documentation, isn't it?

Replies are listed 'Best First'.
Re^2: The sourcecode is the documentation, isn't it? by deprecated (Priest) on Aug 13, 2007 at 17:04 UTC
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.	[reply]
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: Does it work? Can someone else come in, make a change, and be reasonably certain no bugs were introduced?	[reply]