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, biapar, Willr, Ingo, simon_w

Comments in code - style.


Reply


2 Posts   1451 Views

Avatar
mateusz

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.

Avatar
Sam

Administrator, 685 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.