Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??

Wow. I've taken a quick look and really like it!

Given my keen interest in this domain, I read the "Stylish Perl" chapter first. This chapter is excellent as is, and very short (which is desirable). That said, taken from On Coding Standards and Code Reviews, you might consider adding more material derived from one or more of the following.

Cleverness

  • If you must rely on cleverness, encapsulate and comment it.

Design

  • Establish a rational error handling policy and follow it strictly.
  • Coupling and Cohesion. Systems should be designed as a set of cohesive modules as loosely coupled as is reasonably feasible.
  • Data hiding. Minimize the exposure of implementation details.
  • Minimize the use of global data.
  • Interfaces matter. Once an interface becomes widely used, changing it becomes practically impossible (just about anything else can be fixed in a later release).
  • Design the module's interface first.
  • Design interfaces that are: consistent; easy to use correctly; hard to use incorrectly; easy to read, maintain and extend; clearly documented; appropriate to your audience. Be sufficient, not complete; it is easier to add a new feature than to remove a mis-feature.

Maintainability/Supportability

  • Minimize the scope of variables, pragmas, etc..
  • The result of every file operation or API call or external command should be checked, and unexpected results handled.

Commenting

  • Generally, comments should describe what and why, not how.
  • Separate user versus maintainer documentation.
  • Every non-local named entity should be commented.
  • There should be a comment on any code that is likely to look wrong or confusing to the next person reading the code.


In reply to Re: Modern Perl: The Book: The Draft (feedback) by eyepopslikeamosquito
in thread Modern Perl: The Book: The Draft by chromatic

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!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • 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
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            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
    Domain Nodelet?
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this?Last hourOther CB clients
    Other Users?
    Others musing on the Monastery: (3)
    As of 2024-09-14 12:06 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      The PerlMonks site front end has:





      Results (21 votes). Check out past polls.

      Notices?
      erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.