Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Re^2: An Introduction to Literate Programming with perlWEB

by doom (Deacon)
on Jan 18, 2009 at 09:53 UTC ( #737130=note: print w/replies, xml ) Need Help??


in reply to Re: An Introduction to Literate Programming with perlWEB
in thread An Introduction to Literate Programming with perlWEB

Well it seems to me that there are programmers who have trouble doing the mental context switching between "thinking in code" and "thinking in english", and they have a visceral objection to all forms of mixing code and english together (comments in code, pod embedded in code, etc.).

I'm not one of these people myself -- I'm a fan of embedded pod, and I go as far as to say you should avoid working with people who talk about "self-documenting code" with a straight-face... but on the other hand, part of the game of writing code for other people to read is to keep in mind that there are other kinds of people out there. It's not a bad idea to remember that there are "pure code" people around, and so you should do your best to keep comments brief, and so on.

The objections that the "pure code" folks have to mixing words in with your code frankly don't often make much sense to me. For example, BrowserUK likes to complain about the need to maintain code and documentation in parallel, but that problem doesn't go away if you move the docs to another file... in fact, at least in theory, keeping the docs for a sub with the sub is supposed to make it more likely the docs will be changed when the code is. (It certainly works that way for me... but then, Damien Conway claims that it doesn't seem to work in practice, so who are you going to believe?).

Some older threads on this subject, if anyone's interested: Code Maintainability, Programming *is* much more than "just writing code"..

But then, I'm afraid I must agree that pre-processors are a bad idea. I'm a fan of the perl debugger myself -- do you know what it's like to try to debug code that uses a pre-processor? The abstractions the pre-processor was used to implement break down immediately, and you end up steping through the other guys code instead of the stuff you're working on.

In general, I think perl is a very nice, flexible language, which means it can be used to implement variations of itself... but if you take that too far, it doesn't seem to me like programming in perl any more, and I lose interest pretty quickly.

  • Comment on Re^2: An Introduction to Literate Programming with perlWEB

Replies are listed 'Best First'.
Re^3: An Introduction to Literate Programming with perlWEB
by BrowserUk (Pope) on Jan 18, 2009 at 11:26 UTC
    BrowserUK likes to complain about the need to maintain code and documentation in parallel, but that problem doesn't go away if you move the docs to another file

    Oh, but it does!

    When writing documentation in a different file, people are far less tempted to start describing how the code works--opens a file; increments a variable; sorts an array; stuff which all but the most novice of programmers can (and if they are to do a descent job of maintenance work; should), work out for themselves, from the code.

    Instead, they (should) concentrate on:

    • the what: the public APIs and their parameters;
    • the why: their function and purpose, in terms of what they are intended to do on behalf of the calling code;
    • the usage: this one is far to often glossed over or omitted completely.
    • the contract of that API: its requirements of the caller, and promises to them.

    Documentation is for users; and should be written at the same level of abstraction that the user will use the exported api.

    The code is description of the actual algorithms used and their implementation. And should be the only such description. It cares not for the external abstraction.

    You should be able to re-implement the internals of an published (documented) API, using different internal algorithms, or even a different language, and the documentation should not need to be change at all. Nothing in the documentation should need to change, when the implementation changes, provided that the published API is maintained.

    The purpose of comments is to annotate the code with additional (brief) information, pertinent to that code, that the language does not allow to be conveyed easily by the code itself. It should not repeat the code; nor the documentation; nor the language manuals.


    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.

      Well, this is what I would tell you about words and code:

      Unless you're working from a fixed spec (which is more the exception than the rule, I'd say) the API of a module is going to change as you're working on it. If you keep the pod describing what a sub does in the same file as the sub, I think you're much more likely to remember to revise the docs when the API changes.

      Further, it's often a very good idea to use some comments throughout the code. The "paragraph style" works well: a "topic sentence" in english, followed by detailed explication in the form of code. Comments at the end of a line of code are good places for things like TODO notes and even hints to perl beginners ("hash slice", "schwartzian transform").

      As for things like this:

      The code is description of the actual algorithms used and their implementation. And should be the only such description. It cares not for the external abstraction.
      My personal opinion is that techies really need to watch these kind of religious beliefs -- we're always trying to squeeze the world into these neat, idealized doctrines, but the world always fights back. For example, if you were to take what BrowserUK is saying seriously, you would insist that perlguts should not exist.
        For example, if you were to take what BrowserUK is saying seriously, you would insist that perlguts should not exist.

        Au contraire!

        perlguts is a great example, but for exactly the opposite reasons to those you seem to think. It doesn't describe an implementation; the names of varibles used for loop counters; or the algorithm used (for example) to calculate the hash of a key for an associative array.

        It is user documentation describing an API.

        In this case, the users aren't Perl programmers, they are XS programmers. It is, in part, derived from embeded, interleaved tags (in the manner of JavaDoc or Doxegen). But not from embedded prose re-describing the internal implementation. XS is an abstract API, implemented through C macros, and perlguts documents that API at that level of abstraction.

        And to reinforce the power of that abstraction, when Dave Mitchell re-implemented large chunks of the underlying code for 5.10.0, (actually 5.9.something). to reduce the memory footprint of many of the internal structures; Perlguts hardly changed at all. Your own example makes my points above more strongly than I ever have.

        There's nothing "religious", no "neat, idealized doctrines" involved. Just simple, practical, proven methodology derived from hard won experience. Not my ideas, nor my experience, but that of 50 years of those that went before us.


        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.
Re^3: An Introduction to Literate Programming with perlWEB
by tilly (Archbishop) on Jan 21, 2009 at 23:35 UTC
    If you go so far as to say that you don't want to work with programmers who can talk about self-documenting code with a straight face, then you are going to pass up working with a lot of good people. Like me.

    On the subject of documentation and code, I am a big believer in limiting what you document about your code. That does not mean eliminating documentation! But my attitude is that documentation exists for people who do not need to read my code, which in practice means that the public API and important data structures (particularly database tables) need to be documented, and sometimes you need an introductory document or three. What documentation does not exist for is helping people to understand my code. If I need that then I have at least one problem, and if I use documentation to solve it then I have just added another.

    By reducing the amount I document, I avoid a lot of potential mistakes. Furthermore things that I think should be documented, like APIs, are things that you shouldn't be changing in your code without thinking through potential impacts anyways. So asking a person to go and document those changes makes perfect sense. If you stay consistent about what gets documented, when, then in my experience maintaining that documentation isn't too big a deal no matter where it is. And I personally find that documentation to be more readable and consistent when it is kept in one place.

    Even so, documentation will be less reliable than code. But by limiting where I make my mistakes, I know to focus on those potential problem areas. This compensates reasonably well. Since I only need to maintain that vigilance some of the time, it is easier than if I had to think about it more often.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://737130]
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (4)
As of 2018-02-25 22:15 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    When it is dark outside I am happiest to see ...














    Results (315 votes). Check out past polls.

    Notices?