Your skill will accomplish what the force of many cannot |
|
PerlMonks |
Re: The sourcecode *is* the documentation, isn't it?by rir (Vicar) |
on Jun 14, 2004 at 20:33 UTC ( [id://366682]=note: print w/replies, xml ) | Need Help?? |
Update: "Documentation" here refers to documents in the
areas of specification and implementation.
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.
In Section
Meditations
|
|