Think about Loose Coupling | |
PerlMonks |
Re: The sourcecode *is* the documentation, isn't it?by hardburn (Abbot) |
on Jun 14, 2004 at 16:35 UTC ( [id://366603]=note: print w/replies, xml ) | Need Help?? |
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. ----
In Section
Meditations
|
|