I couldn't agree more about commenting and how important it is.
I have two rules that I follow no matter what I code, unless I'm going for a one-line wonder.
- Comments should say why you're doing something, not what you're doing something
- You're never coding something for yourself, but for the coder who will be maintaining it in the future.
These are both incredibly important in my methodology of coding. Unless I'm writing bizarre (or obfuscated) code, I can usually tell what I'm doing with the code. It's not a matter of what I'm doing, but why I'm doing it. Someone mentioned that in a prior response, but they said both what and why, whereas I feel that a "This code does X" comment isn't terribly worthwhile unless there's a reason why you're doing that - and then it's worthy of a comment.
Also, writing code for those who come after you is very helpful, as it keeps people from bugging you with questions about code you've moved on from. ;) A good example of this would be my current position. I've written code that (hopefully) will never have to be updated or maintained. However, that's just a pipe dream. So, since the people who will be coming after me have no Perl experience (cause my boss insists on hiring people with no PC knowledge but with people skills <rolls eyes>), almost every single line of my code is commented with why I'm using a chunk of code there.
Comments are one of the best tools a coder has - use them wisely. :)
~Brian
-
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.
|
