Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Re^2: Programming *is* much more than "just writing code".

by BrowserUk (Pope)
on May 09, 2007 at 05:48 UTC ( #614304=note: print w/replies, xml ) Need Help??


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:

  • Would this comment be useful to anyone other than another programmer working on this piece of code?
  • Would this comment have any meaning to anyone, in the absence of the code?
  • If this code is ported to another language, would this comment still make sense? /li>

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.

Replies are listed 'Best First'.
Re^3: Programming *is* much more than "just writing code".
by doom (Deacon) on May 09, 2007 at 07:51 UTC

    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.

    You're in agreement with Damien Conway on this, but myself I think interspersed pod-style has some strong DRY advantages. Most subs require some verbal description to go with them, and there's some overlap between what you need to say for the benefit of a maintenance programmer working on your code and a client programmer interested in using your code, and it's not at all a bad idea to put that inside an "=item" that goes with the sub. (And I would hope that it is obvious that remarks that are only of interest to a maintenence programmer should be confined to comments.)


    It also creates dependencies.

    The dependencies between the documentation and the code do not go away if you move the documentation elsewhere.


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

    I'm once again, having trouble figuring out what you're getting at here. Nothing about the interspersed pod style I'm arguing for prevents you from writing the documentation first, and in fact I often work that way. Of course, if you use this style you have to present the code in the same order that you want it to appear in the documentation, and that's a problem that would go away in a true "literate programming" language.

    By the way: you do understand that you can embed other markup inside of pod if you want to, right? From perlpod:

    =begin html <hr> <img src="thang.png"> <p> This is a raw HTML paragraph </p> =end html


    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.

    Actually, you should get out of the habit of using __END__ at all: it breaks mod_perl code.

Re^3: Programming *is* much more than "just writing code".
by samizdat (Vicar) on May 09, 2007 at 15:54 UTC
    I agree with you completely, BrowserUK, but especially with two points (my paraphrasing):
    • The best course of action in examining code is to strip out everything but code and format it consistently.
    • Documentation should be detailed and use every tool we humans have come up with for enhancing readability.
    I, too, am a fan of Literate Programming, though I have yet to find the right tool to give me both views of a project. We should be able to switch between pure-code view and documentation view at will, without the messy comment-stripping and PerlTidy steps in the middle. Even better, I'd like three views: pure code, syntax-highlighting with hyperlinked definitions and where-used lists, and documentation view with full text enhancement. Ed Ream's Leo is a step in the right direction, but it isn't all the way there. Mindmaps have documentation advantages, too, as do some CASE environments. I think doxygen is also a great example of the direction we should be heading in this arena. The Xerox PARC Star environment (also Smalltalk/V, Squeak, etc.) with classes and clickable browsers also had excellent usability features, although Smalltalk, the language, was a syntactic mess.

    We have powerful computers these days, with incredibly powerful graphics. I grew up with 7-segment displays and a hex keypad, and I spent much of the first half of my career burning EPROMS on microcontrollers. I have come to believe that, no matter what the ultimate target, fancy IDEs that enhance the programming (and debugging) experience are essential to rapid and effective code development. The need grows exponentially more urgent as teams expand and the underlying hardware, OS, and system interfaces become more complex and critical.

    Don Wilde
    "There's more than one level to any answer."

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (5)
As of 2020-10-21 19:43 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (223 votes). Check out past polls.

    Notices?