Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

comment on

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

Personally, I try to use self explanatory names wherever possible, use my ($various, $param, $here) = @_; for positional arguments, and generally try to write the code in such a way that such information is contained in the code wherever possible. This also impacts the surrounding code - if your functions and methods are well named, the code using them will also be easier to read. My maxime is that if you feel the need to add a lot of comments, then something's fishy about your structuring and naming style. Between the public documentation and the code, not much room should be left for comments on the code.

Write code with as few indentation levels as possible (but break this rule when it makes the code read more naturally), mostly using last and friends. Always name variables sensibly. Avoid having more than two or three subexpressions in a single condition. Do things Once And Only Once, so that you take up less screen space and end up with fewer but more expressive distinct things to understand. Capture regularities in code, irregularities in data. Do the tersest and simplest thing that can possibly work.

These and more, similar ones are the things to strive for when writing code. Follow them well, and you will find that even scarcely commented code is comprehensible.

However,

you should meticulously document your data structures. The clarity of the code hinges on your understanding of the data it manipulates. That is something you should pay very close attention to. In essence, good programming skills means good data structure design skills.

Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won't usually need your flowcharts; they'll be obvious.
-- Frederick P. Brooks, Jr., The Mythical Man-Month

If the data structures are well designed, the code to manipulate them will suggest itself. If they are well documented, the code that manipulates them will suggest its intent with hardly any commentary.

Makeshifts last the longest.


In reply to Re: Documenting Methods/Subs by Aristotle
in thread Documenting Methods/Subs by vek

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 scrutinizing the Monastery: (2)
As of 2024-04-25 02:15 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found