Comment style gallery... post how you style your comments [closed]

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate,开发者_Python百科 arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. Closed 11 years ago.

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.

---

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!

---

A side node (Quick link, not mine): http://www.heartysoft.com/ninja-coding-code-comments

Why I don’t like comments

The main reason I’m trying to avoid commenting my code is the concept of self explanatory code. Code should be self explanatory – anyone reading the code should understand what’s going on (given some domain knowledge, of course). Relying on comments to explain what’s going on is hardly a good idea. Code is going to change far more often than comments getting updated. No matter how vigilant your team is, this is bound to happen. At best, this can result in slightly outdated comments. At worst, stale comments may be entirely misleading to what the code is actually doing.

--

I am always trying to refactor my code so that it does not need any additional description.

So I end up with having hardly more than the usual xDoc comments to autogenerate the APIDoc. Even these comments can be autogenerated to a large extent.

In corner cases (e.g. OS specific issues) I try to find a public website discussing the problem and add a link. If the link breaks in the future time - shit happens.

--

AS3:

/**
 * This is a usual doc comment for a type or property.
 */

/*
 * This is a marker of a particular longer section of code.
 */

// This is a single line comment before a or at end of a line of code.

---

In AS3, I use this:

/**
 * 
 * to comment (if necessary) a method or a group of related methods
 *
 */

while I use this:

//

for single line comments.

Furthermore, I usually insert empty // comments to gain a little more code readeability.