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??
targetsmart:

Your code should be written to be as clear as possible, as it's supposed to adequately explain *what* it does. Normally, the types of comments I use are:

  1. Section breaks to show when I'm "shifting gears" in the code. (Such as "Initialization section", "Process results", "Print reports". These aren't really necessary, but I find them a handy way to segue between sections.)
  2. References to algorithms I intended to implement, if they're unusual. These will normally be in the comment header for the function.
  3. Specific and implied business requirements. This is the most important type of comment in my view. Business logic and programmer logic are quite different at times, so code that looks obviously wrong can be correct and vice versa. If the line of business specifies that you define "Gross Annual Sales" as the number of items you sold last Tuesday, then that's what you have to deliver. (No matter how Marketingesque the logic is.) Implicit requirements are also important--these are the ones where you have to work around flaws in other subsystems or business processes.
  4. Assumptions I'm making for input. (Gee, I assume that all our products are *heavier* than 0kg. I hope we don't start selling Helium balloons or this routine will break!)

Of course, commenting styles are varied, so this list is strictly my opinion...

...roboticus

In reply to Re: Why no comments? by roboticus
in thread Why no comments? by targetsmart

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 exploiting the Monastery: (9)
As of 2024-04-18 16:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found