xulwidgets
| resources: | Home Mailing List Installation Manual Test Cases Source Code Members Bugs Screenshots |
|---|
Coding Conventions
XUL Widgets requires a slightly more rigid set of coding conventions than most chrome developers may be used to. Fortunately, none of this manual has been written without consideration for developers. This manual has been written in conjunction with XUL Widgets's development, and especially in conjunction with working code. Simply put, if you're reading something in the manual that hasn't been implemented yet, it's a bug in the manual, a violation of a contract between the developer (you) and the project.
Errors and warnings
There's a simple rule of thumb: throw errors and exceptions only when someone misuses your code.
No XUL Widgets core code or extension should ever have JavaScript strict warnings in it. Any errors or warnings that actually get to the JavaScript console service should have a bug report on file.Source-code documentation
If another competent developer cannot easily understand what
you're
doing at a certain point in the code, you need to comment the code
better at that point. File bloat will be explicitly
encouraged for documentation as comments. Note the word
"competent", though: if a developer doesn't understand DOM
Level 1 Core, then you don't need to comment about what setAttribute()
does.
JavaDoc comments
Use them. Follow the spec. Every function should have JavaDoc commentary on it.
For XBL bindings under the <implementation>
element, use the following format, based on JavaDoc:
<!--*
* Function description.
*
* @param firstArg The first argument.
*
* @return Boolean true if the first argument is a number, false otherwise.
-->
Documentation in this manual
Every feature of XUL Widgets must be documented in this manual for the XUL application developer. Documenting for developers is also recommended, especially where source-code documentation and JavaDoc comments are not adequate.
Test cases
Every XUL widget must have a testcase for it, living in (topsrcdir)/xulwidgets/src/tests/ as a chrome-based testcase. In addition, wherever possible, remote XUL testcases for each XUL widget should be available under (topsrcdir)/xulwidgets/www/testcases/ as a web-based testcase.