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:
If I were trying to address the issues of metadata in a large environment. I would put data like this into a code generating environment of some sort.# 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" ) ."."; }
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" ) .".";
In reply to Re: The sourcecode *is* the documentation, isn't it?
by rir
in thread The sourcecode *is* the documentation, isn't it?
by dimar
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |