|Welcome to the Monastery|
Re: Programming *is* much more than "just writing code".by graff (Chancellor)
|on May 09, 2007 at 02:59 UTC||Need Help??|
Comments serve a different purpose to documentation. And documentation does not belong in source code files.
Are you talking about Perl here? Are you saying that using POD in perl code is wrong in some way? I cannot agree with that. (And just where should the documentation be?)
Okay, programming is hard, and writing proper documentation is at least as hard -- often harder: striking the right balance of natural language coherence and logical/procedural accuracy is really another form of the common tasks in programming: problem-solving, puzzle-wrestling, optimizing, getting things into the right operational sequence, working out the best way to refer to things, and so on.
(Let's face it, every higher-level programming language is really a sort of subset or reduced adaptation of a human language, designed to make control of computers possible for a wider range of humans, and easier for the ones who really understand the machines. Comparing this to mathematics, chemistry, etc, is disingenuous -- people in those fields need text books, in a human language that they know, in order to learn the symbols and the syntax for combining them. And that's a lot of work!)
So doing both the code and the documentation -- and maintaining both of them to keep them in sync -- is really hard. But that's a lousy reason for not doing it, and based on experience, I tend to believe that the code is easier to write (and to get right more quickly) when the documentation has been written first, and is as clear and unambiguous as the code needs to be. What I mean is: the coding is less work when the documentation is done first.
An added nice feature about that, when you're able to do it, is that you can show the docs to people who don't know how to program (e.g. a customer or sponsor), and assuming you are dealing with people who know how to use the same human language that you are using, they can understand it, react to it, make suggestions for improvements, and so on. Even though the population proficient in any given human language is "limited", it's a lot bigger than the population proficient in a given programming language -- English, French, etc are good for somehting, even to programmers.
And a nice thing about doing it as POD in your Perl script is that it's always right there for you, the programmer, and it's also really easy to present to others, the non-programmers, in a clear, human-readable form.
When time/money are limited, and you can only do one thing, then obviously it's better to write the code rather than the documentation. But then you get what you pay for, which is probably going to be about half of what you really need.