Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
If you were trying to grok the flow of data through several classes, and through perhaps 10 or 20 methods, . . .

Lord and Lady preserve us! How complicated are you making your code?! If I have to do what you're suggesting, that is a CodeSmell and needs to be addressed immediately, preferably through refactoring the living #$E*! out of it. I should be able to look at a test and see exactly how I'm supposed to use any portion of your code. Period, end of story. Otherwise, either your tests or your design sucks. (Or both, but if that's the case, then you're better off starting from scratch.)

Remember - we're talking about the non-public portions of your API. This is the stuff that you don't want the average client using. Since the intended audience is a developer, they should be looking through the tests, anyways, to understand the assumptions you've made that your code won't document. In addition, they probably are looking through your tests in order to figure out how to test their modifications to or subclass of your stuff.

Furthermore, I'll point at DRY (Don't Repeat Yourself). A purpose-built summary is, by definition, a repetition. It has to be kept in sync by hand and thus, by definition, won't be in sync. The tests, on the other hand, are part and parcel of the code in question. If the test suite passes (as it always should), then I know that the tests are the best possible form of documentation the developer could have provided. (They're even better than any comments that might be in the code.)

While we're on the topic, the documentation for the public API should consist of the following:

  • What is this thing (NAME)
  • Basic usage (SYNOPSIS)
  • Ideas behind it (DESCRIPTION)
  • Details about the names of the methods and the various options (METHODS)
  • Common uses (EXAMPLES)
  • Anything else the client should know (BUGS/CAVEATS)
  • How to get more help (CONTACTS/AUTHORS)

No more and no less. (Any similarity to the standard POD skeleton is completely intentional.) At no time should any reference be made to implementation details, save when one public method calls another public method within the same module (and that should be done sparingly). Private methods should never appear, save when they violate some community contract (such as having "new" or "clone" be a private method) or some Perlism (such as having "print" be a private method). And, frankly, if you have to document a private method in your public API, that's a DesignSmell and should be addressed ASAP.


My criteria for good software:
  1. Does it work?
  2. Can someone else come in, make a change, and be reasonably certain no bugs were introduced?

In reply to Re^3: Documenting non-public OO components by dragonchild
in thread Documenting non-public OO components by creamygoodness

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



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
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 admiring the Monastery: (4)
As of 2024-03-29 10:13 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found