• to include such documentation means to balloon the size of the source code
• to include such documentation means to write two different versions of the *same thing* (thus violating the virtue of laziness)
• to include such documentation means to constantly make sure the docs are in synch with the code

These points are true of almost any documentation system.

the author of this demo code does not use POD, perhaps because he is sick of having to use a different documentation system for each prog language, and instead uses this same style for every environment

IMHO, the actual implementation of such a system will vary so widely between languages that you might as well learn the language-specific documentation system anyway.

should the author be persecuted for not using POD?

Yes.

is there really any such thing as 'self-documenting' code?

Code which is programmed specifically for clarity. This might be a Holy Grail which is never reached, but at least we can better ourselves while trying to reach it. As a last resort, we have comments.

does anyone out there really care about this stuff at all?

Not really. Classes need their complete public interface to be documented, because someone shouldn't have to read the raw source code to understand how something works. Other than that, code documentation is really only needed when something tricky or non-obvious is going on.

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.

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?

This topic has been the source of many spirited conversations where I work. What goes into a design doc? What goes into a user manual? What is the appropriate level of comments for code?

I personally find that a user manual should only tell the user what they need to know to use the tool (or library, or module, or class...), not anything about the internals (too much information, and the documentation won't be read). POD seems to be a useful way, and I would always recommend it.

When it comes to design documents, some people I work with state quite emphatically that their design document is the comments in the code. IMHO this is not sufficient. If I suddenly have to maintain someone else's code, a roadmap would be nice (i.e. these files contain the code that does x, so if x breaks, this is where to start). After that, the specifics of the design I do expect to find as comments within the code.

With regards to comments in the code, some of my co-workers write books at the header of each function/class. Others insist that there be a comment for practically every line of code. I, however, being rather old school, learned my habits before syntax highlighting full screen editors were available. The criteria for my commented code is: (1) use lines to outline main comments, and (2) the comments should read like a very general algorithm.

The reason I like my commented code to read like an algorithm is very simple. When I go back to it to add new stuff (there are always new requirements) or especially when looking for a bug, I can verify that the code does what it is supposed to do (as determined by the comments). If I don't know what it was meant to do, then it is much harder to know whether or not what it is doing is what it should be doing.

I have written parsers (in FORTRAN for FORTRAN) that would extract the comments, and then used the results for detailed design reviews. I found this to be very useful. To this day, before I consider a project finished, I will pass through one more time, ensuring the the comments reflect the intention of the code.

to include such documentation means to balloon the size of the source code

Sandy

Here is a piece of advice I find has merit:

Let the source code say what you are doing, add comments to say why you are doing it

Let the source code say what you are doing, add comments to say why you are doing it

I totally, completly agree with you. There's no worst comments than those duplicating informations given by the code since usual coding practices tend to make forget having them synched.

Until you're not a Befunge of APL developer, the language you code with has usually enough semantic elements helping you to understand what is meant in there.

Nota: English is not my mother longue but I can manage to understand approximatively what is meant here without any comments available :-)

HTH, Dominique

Let the source code say what you are doing, add comments to say why you are doing it

I'd go a bit further and say that if you have to add comments to explain why you're doing it you should reconsider and see if there way you can rewrite your code to express your intentions more obviously.

Comments are a good thing if they make non-obvious code easier to understand. Even better is to make the non-obvious code more obvious.

uses this same style for every environment

This style could be done inside POD instead of a Perl if statement with a slight gain in clarity. Just putting the if on top would help.

structured to be easily machine-parsible, and therefore usable in different contexts

But it is still not trustworthy.

such documentation means to balloon the size of the source

This is concise to me.

to include such documentation means to write two different

This is a problem of any documentation.

means to constantly make sure the docs are in synch

This is a problem of any documentation.

informal anectdotal psuedo-survey reveals that 'self-documenting' features of prog languages in general is one of the *least utilized* features for many production environments in the 'real world'

And something like three of four products fail to be created. My experience is limited but I tend to accept your pseudo-survey's accuracy. So what. That the masses don't use a feature indicates nothing about the quality of the feature.

Funny how the author can not be bothered to use Perl's integrated documentation features.

should the author be persecuted for not using POD?

Not really, firing for insubordination is sufficient in the business world. If the this is independent work and the writer can draw enough interest to make this an issue good for him.

is there ... such thing as 'self-documenting' code?

Perhaps in very limited problem scopes. Otherwise there are always areas where the constraints of a computer process impinge on the preferred conceptual model/solution.

It is a fine thing to strive to have the code and the documentation become one. What you are showing is code and documentation which are lexically adjacent; often the best that can be achieved.

what is an easier way to write source code that can be queried *itself* as if it were data or documentation?

I am not sure what you mean. I think things with encompassing IDE's (integrated devel. envir.) sometimes try to reach this, perhaps smalltalk. Eiffel tries to do this with its assertions, pre-conditions, etc. Knuth's Literate Programming is a tangled web you may wish to explore.

does anyone ... care?

Yes, Ugol's Law is applicable.

I don't find the sample convincing. The common problems of documentation survive. The name is bad; DispGreeting doesn't display anything.

I would write this more like:

# off hand code

sub make_greeting {
    # Return a greeting string, by default greet the world.

    croak "Bad parameter count to make_greeting" 
        unless @_ <= 1 and DEBUG;
    return "Hello " . ( $_[0] or "world" ) .".";
}
[download]

function:  
    name: make_greeting
    scope: intra-language
    descr: Make a greeting to designee or, by default, world.
    doubts: Locale issues await. Low-level func.--orphan?!
    parameter count: 0-1
    parameters:
         param: name
             ord: 1
             type: string
             descr: Name of recipient of greeting
    error: die
    languages: perl
    type: string
    perl:  return "Hello " . ( $_[0] or "world" ) .".";
[download]

Although reasonable people can differ on some of the finer points, this response hits the nail on the head and draws out a lot of the contentious issues ... issues that strangely draw the ire and resistance of many for some strange reason.

case in point: the 'large environment metadata' sample you provided is almost (if not entirely) optimal for the type of concise, accessible specification one would hope to see in a 'professional' environment. (plain, forward-looking, demonstrates competence, provides useful audit trail)

Yet, I would bet money that few if *none* of you in the larger environments (I'm not naming names here) have *ever* inherited a project that was completely and coherently covered in such a straightforward manner. This is especially so for projects consisting of largish teams with oversight from multiple (departments/camps/competencies); *specifically* the context where this sort of approach is most cost-effective and beneficial.

Someone once said, in technology, that the best approach is (usually) (always) the one that never sees the light of day.