Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re^6: An Introduction to Literate Programming with perlWEB

by doom (Deacon)
on Jan 21, 2009 at 20:17 UTC ( #737930=note: print w/replies, xml ) Need Help??


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

Okay, you have a point, but my claim still stands: there is nothing wrong with documenting internals, and that's certainly one of the ways in which perlguts is used: it's recommended reading for beginning perl-porters.

Will the actual state of the code drift from the internals documentation? Yes, certainly, but that doesn't make the docs useless-- at the very least they tell you something about where the codebase was at an earlier stage. When you're getting used to an unfamiliar code base, any hints at all are worthwhile.

And I would suggest that what the perlguts example really illustrates is that the distinction between internal and external is fuzzy, because that boundary moves around depending on what you're doing -- to an XS programmer, perlguts is the API, to me, it documents some internals I don't need to think about just now.

Note that if you put every routine into it's own module with it's own API to document, then there would be little difference between your position and mine.

There's nothing "religious", no "neat, idealized doctrines" involved. Just simple, practical, proven methodology derived from hard won experience.
That's what they all say.
Not my ideas, nor my experience, but that of 50 years of those that went before us.
You mean the experience of guys like Donald Knuth?

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

Replies are listed 'Best First'.
Re^7: An Introduction to Literate Programming with perlWEB
by BrowserUk (Pope) on Jan 22, 2009 at 12:12 UTC

    When you're getting used to an unfamiliar code base, any hints at all are worthwhile.

    If you put every routine into it's own module with it's own API to document, then there would be little difference between your position and mine.

    On any project that runs to more than half a dozen files, there is absolutely a need for project documentation, separate from, and with a different target audience to User/API documentation. Targeted at maintainers, this should include such things as file layouts; internal structure layouts; the structure of the project directories and files; build, test and validation procedures etc.

    But when you're first sitting down to explore and familiarise yourself with a project of this size, the last thing you want to have to do is stab around in the dark peeking inside source files at random trying to piece together an overview by picking out those bits of the embedded prose that relate to that overview, from those bits of that embedded prose that relate only to the local line, block, subroutine or file.

    Not only does that make it difficult to form a coherent overview of the project initially. That difficulty persists throughout the life of the project for all concerned. Everyone--from programmers, to architects to managers to technical writers--waste an inordinate amount of time trying to remember not just what they read, but where they read it. It is all but impossible to index the information at any given level it for any target subset of users.

    This type of project overview or architectural site map, absolutely does not belong spread across myriad source files mixed up with "this loop counter is unusual because it starts at -1" type local annotations.

    You mean the experience of guys like Donald Knuth?

    Hm. He has seriously long and deep experience yes, but of a very different kind to your average Joe Programmer, systems analyst or project architect.

    It all comes back to my short answer in my original reply above.

    His uses and needs of a documentation system are far and away different to those of your working stiff programmer or project leaders. He's targeting an entirely different type of audience; his goals are: absolute technical correctness, and understandability by first-year undergrads regardless of background; his timescales are measured in years, if not decades, rather than the days or weeks as for most commercial projects.

    This puts me in mind of a heated discussion I had a dozen years ago with the head of HR for an extremely large organisation. Try as hard as I might, I could not convince her that two years of relevant experience was far superior to ten or more years of the irrelevant.


    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.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others musing on the Monastery: (7)
As of 2018-06-19 20:10 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?



    Results (114 votes). Check out past polls.

    Notices?