There is no correct way to comment your code. Your comments should state what the code below it does in plain English. Don't make a novel or anything, just tell the next programmer what is going on. When making a variable, just comment on what its purpose is.
I'm crazy when it comes to commenting, and not because I'm worried about other programmers, since other programmers generally don't have their hands on my work at this point - it's for my own purposes that I comment, because no matter how into a particular method I am at the time, where I can see everything visually working together in my head, and it flows like this mornings coffee, two weeks later I can come back to something and sit there cross eyed for half an hour trying to figure out what I did if I didn't comment it.
There's three types of comment constructors (delimiters? hmm) you can use in PHP, just to rehash, there's /* -- */, // and #. Typically I use the /* version for the large descriptive comments I use at the beginning of all my library files, and for method comments (where I list the function name, the arguments it takes and what it should return, along with an area for notes as I'm in the development process) and then I'll use // for comments that are littered about elsewhere.
This is just one way of going about it. The actual correct way to do it... is... wait for it... however you want. What looks best? What's most readable? If it winds up adding more clutter and making your readability go down, then chances are you should try another way.
I'm going the 'standard way', if PHPDoc has become a documenting standard. Why? Well, because I use a fully compatible IDE that recognizes the PHPDoc syntax and helps me in development (mainly), because you can generate a thorough HTML documentation without having to actually go through the code manually, and that's about it for me.
I have optimistic thoughts, even though sometimes (if not always) life's a bitch.
I'm fairly simple with comment, I use it allot but just to make it quicker to understand for myself if i havent touched the code in months.
This is how I commented my blog frontpage:
// Jimnet blogging system
// By Jimmy Bokhove, Minna Media <xxx>
// Create a blog by template
// Get Configs
// Get functions
// Get classes
Location: Beware of programmers carrying screwdrivers
I also use the PHPDoc blocks method of commenting code. Using this for functions and class variables primarily.
Normal comments on the rest of the code as people will always need to read the code, and commenting helps in situations which could be confusing to a new programmer.
If you use an IDE such as Eclipse, ZDE or PHPEd, these comment blocks can come in handy when you are working with a project. -- You can even use a plugin in most PHP IDE's to generate code documentation based on your PHPDoc blocks.
I'm also crazy when it comes to comments not because I worry about other programmers, and other programmers usually have jobs my hands right now - this is for my own needs, I commented because the issue in this way I am particularly when they can visually see all work together in my head and pour the coffee in the morning, after two weeks, you can return to something and cross your eyes to stay there for half an hours trying to figure out if I do not comment.
There are three types of constructors (separators comment right?) Can be used in PHP, restatement, no / * - * / and / / #. Usually, I use version / * descriptive comment for large I use at the beginning of all my library files, and comments on the method (if I enter the function name, the arguments they take and he must return with areas of note, while I'm in D), then I'll use / / for comments, which were on the other side.
It's just a way to make room veschi.Realny doing things ... it ... wait for it ... However you want. What looks better? What could be easier to read? If you find yourself adding more confusion and make readers down, chances are, try another way.