Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

Archive /

Our old forums are still available as a read-only archive.

Moderators: martimiz, Sean, Ed, biapar, Willr, Ingo

Comments in code - style.

Go to End

2 Posts   1646 Views


Google Summer of Code Hacker, 27 Posts

28 June 2007 at 6:52am

I would like to know what style should we use in comments. I suppose that we should use phpDoc attributes but I would like to know which of them are necessary. The same question I have about Javascript.


Administrator, 690 Posts

28 June 2007 at 10:52am

Generally speaking, @param and @return are sufficient.

* Short description of the class/method.
* This is a longer explanation of what the method does, be sure to include any
* assumptions that it makes; if it's designed to be called from some particular
* place, it's worth mentioning that too.
* @param something This is a variable What should it contain?
* @param other This is a variable. What should it contain?
* @return Explain the return value

JavaScript doesn't currently have documentation auto-generated for it, but using a similar format to the PHP docs just keeps things consistent.