commenting my code

say i have quite a few pages, and i need to comment them, what should i do with the code that is same in different pages? comment them all or just one instance of it?

further more should i go overboard and do this:



or

I think it depends on the code you're commenting. If it's just a personal project and you'll be the only one to look at the code in the project, I wouldn't bother commenting code which is the same in multiple pages. Just do the one and ignore the others (perhaps add a "see thisfile.php" instead). However, if it's something more important where other people may be looking at your code perhaps it may be better to comment it more fully, so that anyone else looking at your code knows what's happening, without having to start working through every file.

When it comes to actual commenting, I'd go with your second option, I think the first one is overboard. And I probably wouldn't bother commenting obvious statements like "if ($row) {", since I think anyone looking at that should understand what it means.

But it's quite a personal thing I think, so in the end, do what you feel most happy with.

I try to use variables and functions that tell me exactly what is going on. For instance, if I have a table with user_ids and names, and I want a function that gets a user name given a user id, then i'll name it "GetUsernameFromID()". Makes my life easier, and keeps me from commenting too much. This goes for form names as well, or any attribute that is worth remembering. In fact, I get myself into such a pattern that even with over 50 functions, I make the correct guess 95% of the time.

On the other hand, if you have code that is complicated and worth commenting, take the time to do it. It will make you feel more familiar with it. The more you think about it, the better chance you'll have of simplifying it.

However, if you notice a complicated chunk of code that is worth commenting in multiple pages, I suggest using includes. Of course (from what I understand), you couldn't do this without a scripting language.

My final note: don't forget that comments that might make sense to you probably don't mean much to other coders. It's tough reading someone elses code. I can't do it - ever. So if you are developing with a group of people, come up with some standards.

Oh yeah, here's a Slashdot thread I bookmarked a few weeks back: a number of people express their opinions and ideas about commenting. You might check it out: Slashdot Thread

thanks ppl, the comments are supposed to be put on my coursework. so it is gonna be a one hell of a job going through and repeating myself page after page :yawns:

I had a professor that was very strict about comments. It was a pain, cause we'd code everything and add them in at the very last minute. Taught me that you have to follow rules in the real world if you want to keep your job.

For my latest project (just a personal thing) I decided to comment my code something like as follows:

' ### Section 1.0 ###

Code etc here

' ### Section 1.1 ###

Code etc here

' ### Section 2.0 ###

Code etc...

It might be slightly overboard but I am trying to get a modular design to my code - its only ever going to run on my computer and I want to make sure that I understand what on earth I was thinking when I come to look back on it in a few weeks/months time. I have a Word document that goes with it that explains the arbitary/confusing parts of the code in a bit more detail. I also use it to log error messages I have recieved/could receive in future, and what the solution turned out to be.

Its overkill yes, but it works for me, and as I say, I think I'll be grateful for it when I come to add code in future, and want to get it in the right place!

Happy coding,

Porky