Code Comments?

[saidbakr]

Hi,
It seems a stupid question, to ask, How can I write a meanningfull and understandable code comment?
Are there any rules for writing code comments?

Usually, I write some code comments. However, when I come back to modify or add some features to
the code I already wrote it, I feel that I have forgot the logic which I used to write this code,
What's this Variable? Oh What does this function do? I spend some time to get this back into my mind.
I know the answers for these questuions sholud be already written as comments, but how can
I handle this during coding, speacially, I'm still newcomer to php and nearly every line of the code,
can be regarede as a problem I should search for its solutions. i.e The final code is not ready
when I started to write.
If there any articles or tutorials cover that issue or even your own experience about this,
please tell me.

[Pig]

Don't comment on the obvious.

//get the first 4 chars
$new_var = substr($old_var, 0, 4);

That comment is pretty pointless.

Anytime you create a function, make a comment about what it is supposed to do, and what it is expecting. Even if you don't remember how it works, you'll know how to use it.

If you are going to do something convoluted, explain what you are doing first.

If you have to work with a bunch if numeric keys, make sure you note what they really represent.

Learn to write clear and well formatted code. If you layout code logically and clearly you'll remove the need for some commenting.

HTH