Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister
 
PerlMonks  

Re: Why no comments?

by roboticus (Chancellor)
on Jan 31, 2009 at 14:40 UTC ( #740429=note: print w/replies, xml ) Need Help??


in reply to Why no comments?

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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://740429]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (5)
As of 2019-10-19 00:50 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?