Beefy Boxes and Bandwidth Generously Provided by pair Networks
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??


in reply to The sourcecode *is* the documentation, isn't it?

  • 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.

----
send money to your kernel via the boot loader.. This and more wisdom available from Markov Hardburn.

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

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://366603]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others contemplating the Monastery: (4)
As of 2024-04-25 13:11 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found