Question

I love looking through other people’s codes and see how they style their comments, most people use a mix of * and ////, and of course it all depends on the language, but I have definitely seen some good ways to comment and some bad ways. A coded page can really come together with the right commenting structure and make it really easy to read for someone coming into a project without any knowledge.

I am curious to see what people think are the best way to style comments, section divisions, etc. This could be for html, php, or anything else really.

Answer 1

PHP:
Personally I use // for everything inside of a method/function. It is annoying if someone uses /* */ because it makes it more difficult to comment out blocks of code

For documentation purposes I use what phpdoc uses which is very similar to javadoc.

/**
 * Overall description
 * @keyword - description
 */

Usually a good rule is, if you go 15-20 lines without any comments, you need to put in some comments unless the code is truly self explanatory. While at the time you may think you’ll remember your 500 line function and everything it does you often time won’t. If it is someone else trying to come in and understand your code, it will only be harder for them!