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.

We're retiring the forums!

The SilverStripe forums have passed their heyday. They'll stick around, but will be read only. We'd encourage you to get involved in the community via the following channels instead:

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   1647 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, 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.