http://www.perlmonks.org?node_id=614304


in reply to Re: Programming *is* much more than "just writing code".
in thread Programming *is* much more than "just writing code".

Are you talking about Perl here?

Yes.

Are you saying that using POD in perl code is wrong in some way?

It depends, but essentially: yes.

Firstly, I am not a fan of POD-- leastwise, not in it's current Perl 5 form--but that's a different issue.

Secondly, there are many forms of documentation. Comments are (should be) explicitly confined to annotating the code. That is, this particular piece of code, in this file, Preferably on this line. Anything more than this should be dealt with in documentation--somewhere else.

At the very minimum, documentation should be moved to the bottom of the source file. Interleaving it with the code, detracts from the code in ways that go far beyond just interrupting the programmers overview of the code. It also creates dependencies.

I cannot agree with that.

Fair enough.

(And just where should the documentation be?)

In a separate file with the same name as the source file but with a different extension. That is, the unit documentation.

System documentation should exist at the system development directory structure.

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.

Sorry to be pedantic, but my meditation was addressed to comments, not documentation. and as I said: Comments are not (and should not be) documentation.

Simplifying, for the purposes of discussion, some questions to ask when deciding what is comment and what is documentation are:

If the answer to any of these questions is yes, then that comment is not a comment, but documentation. As such, it should be a part of the documentation set, not tucked away in a comment where it will never be seen outside of the source file.

(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 --

Sorry, but I strongly disagree that it is disingenuous to compare these notations.

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!)

And programmers do not?. They need text books (or their electronic equivalents), to learn how to program.

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,

Again, I am not questioning the need for, nor resisting doing, documentation. I am saying that comments -- # words more words etc. is the wrong place for documentation.

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.

I totally agree with you, but writing documentation in comment cards is wrong.

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 something, even to programmers.

But not for describing algorithms. It is too imprecise. Too shaded with (mis)interpretable meanings. Too complex and vague.

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.

If you place your documentation in (for example) POD, that's true, but if you place it in comments, the only way anyone sees it, is if they look in the source file. Again, you are failing to recognise the distinction I make between comments and documentation.

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.

I find this to be an artificial distinction. I've never yet worked on a commercial project where time and money were not limited.

I also think that no plan survives first contact with the enemy. That is to say, documentation written at a level that prescribes the implementation of any given subroutine, function or class, in advance of the first attempt to implement it, is usually so far from reality that it is next to useless either in writing that first implementation, or for maintaining it once the code is working. Without serious work, it rarely if ever reflects the realities of the implementation.

But in any case, you are still confusing my meditation on comments with something relating to documentation. Nothing I said precludes, nor denigrates the writing of documentation. Indeed, I said in my meditation that "documentation was vital".

All I said that related to documentation, is that comments are should not be used for documentation purposes. And that source files are not the right place for it. I will concede that, if you think that embedding documentation in code (POD) is a useful concept, then keeping that documentation in the same file as the source has some merit. Not much, but some.

However, I strongly feel that the practice of interleaving code and documentation is a bad one. If you must keep it in the same source file, at least keep it all together. Preferably at bottom after the __END__ mark, though that is impossible if the code uses a __DATA__ section.

Personally, I think that POD has it backward. If you want to go with the idea of containing code and documentation within the same file, I much prefer the Literate Programming concept of having the interpreter/compiler simply ignore everything outside of some equivalent of <code></code> blocks, as is used by Haskell, D and others. This allows you to write the documentation first, in whatever markup it adopted by the project, and using the full power of that chosen markup.


Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.