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:
- 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.)
- References to algorithms I intended to implement, if they're unusual. These will normally be in the comment header for the function.
- 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.
- 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
-
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.
|