Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
Although I agree with Abigail-II's answer to DIY Tie, I truly wonder whether looking at the source code of your favourite module would be the best thing to do to learn programming. Generally speaking, anyway.

Suppose your favourite module is CGI.pm. Ovid already described its coding quirks before. Would you learn something from it? And if you would learn something from it, would it be considered "good" by current coding standards (whatever they are?).

Personally, I always attempt to document my programs / modules in such a way that they may actually teach something to the people actually looking at the source. Why I do this? Habit, really. A habit I thought myself, because I've had the "pleasure" to have to look at my own source code more than 5 years after I wrote it. And the first time I had that pleasure, I was cursing the author (that would be me) for not having documented the source a little better. So I started documenting my source extensively. Some might say, excessively: to them I say, pipe the source through PerlIO::via::UnComment! ;-)

Getting back to the reason for this meditation. I think there are legitimate reasons for not suggesting more or less "naive" users to look at the source of their favourite (standard) module as a learning experience. Here they are in what I think is in descending order of importance.

The Cons

Historical deformation
The code of most of the standard modules was originally written for Perl 5.0, possibly before that. Lack of certain features then caused the code to be written in a certain way (e.g. lack of our) or would execute without issuing warnings (e.g. lack of warnings.pm). New Perl programmers looking at these modules, will take over these bad idioms. Cargo-culting results.

Hardly any internal documentation
Many of Perl's core modules lack almost any internal documentation. And I'm talking the Perl source code components here, not the XS code. That is generally even worse. If you learn something from such a module, you generally only learn "what" it does. Not necessarily "why" or "how" it does it. More cargo-culting results. I see the following reasons why there is not a lot of internal documentation in those modules:
  • Execution speed: having to scan through documentation costs relatively more time: that may have been a problem then, it isn't anymore now. In that sense, mod_perl changed the game significantly.
  • The initial developers of Perl were even more of the "Those who can, do. Those who can't, teach" types. If you don't understand the code, you have no business seeing it.
  • Mistaken productivity. If you don't have to document your code, you can program more lines per day.
  • Laziness. Generally considered a good quality when programming in Perl. I consider this to not be a good quality when it comes to documentation, though.

Changed optimizations
For example, in the first versions of Perl 5, method lookup with objects was notoriously slow. Instead of calling subroutines as methods, you would call them as subroutines (adding the object as the first parameter) if you were certain which subroutine would be used to handle the method call. (And yes, I have been guilty of that). Of course, this breaks sub-classing and thus general module re-usability. But it works and was much more efficient then. You don't want people to do that anymore with new Perl code. Still more cargo-culting.

On the other hand, I do think there are a number of reasons why it would be a good idea to expose "naive" Perl programmers to the inside of their favourite modules. In descending order of importance:

The Pros

Exposure to other ways of doing things
By looking at other people's source code in general, you are likely to be exposed to other ways of doing things. Things you knew were possible, things you didn't think were possible at all but turn out to be just a little hard in Perl.

Historical perspective
By looking at older source code in general, you can get an appreciation on how things used to be before they came as good as they are today. And it will hopefully also let you realize that what you consider good now, may be superceded by something much better still in the future.

It's all done by someone, somewhere, sometime
Too many times, users of Open Source software in particular, seem to forget that all the stuff they're working with, has had to be programmed by someone, somewhere in time. And it cost them a lot of work to get it right. Hopefully this will instill some sense of appreciation. We stand on the shoulders of giants, indeed.

Of course, I'm wondering what my fellow brethren would have to say about this matter.

Liz


In reply to Reasons for looking at your favourite module's source by liz

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others taking refuge in the Monastery: (5)
    As of 2014-09-21 10:05 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (168 votes), past polls