Saturday, January 12

on commenting your code

Speaking about an action and doing an action are two entirely different things. As such, whatever you say, will never change your actions (if your behaviour is reprehensible, no matter how you justify it, your behaviour is still reprehensible).

More than that, when you feel the need to justify yourself, this should tell you not that your action is just because you managed to justify it), but quite the opposite: if it actually were just, you wouldn't feel the need to justify it.

This is why I don't believe in commenting the purpose of your code.

The code should be the comments; that is, it should be self-evident what the code does, by looking at it.

There are, probably some border cases when this doesn't apply (when writing libraries you need to comment the public API for example), but usually, obscure code just tells you of poor coding style.

Adding comments to obscure code is not bettering the code; it's just a justification. As such there are some cases that you need to verify, to see if you need to revise your coding style:

Your (older) code is unclear to you. When you pass through it, you need to add comments to it, to make it clearer.

To summarize:
.A Lacking comments are not the problem; What you need to do (if the code will still need to be modified in the future) is to seriously consider refactoring it.

.B It may be that your code is clear to you, but not your coleagues. Not only is your coding style poor, you don't even know enough to realize your coding style is poor. More, you don't even know enough to feel your coding style is poor. <<GOTO .A>>

.C It may be that your code is clear to you and clear to your coleagues.
Stop deluding yourself!

No comments: