Code Guidelines
From OpenLaszlo
The following general coding guidelines are provided for contributions to the OpenLaszlo platform:
Naming Conventions
- Standard Directories and File Naming Conventions
- all files and directory names must be lower case
- Class, Variable, Method Naming
- camelCase: id, methods - class names: all lowercase - attributes, events,names: all lowercase - Constants in ALL_CAPS using underscores
- Resource Naming
- module prefix + name + _rsc , for example: mail_gridhdr_rsc
Code Style/Structure
- Do not use tabs. This will break the builds.
- New LZX files must include the Laszlo Systems copyright at the bottom of the page and the version string identifier, as shown here.
<!-- * X_LZ_COPYRIGHT_BEGIN *************************************************** * Copyright 2005 Laszlo Systems, Inc. All Rights Reserved. * * Use is subject to license terms. * * X_LZ_COPYRIGHT_END ****************************************************** --> <!-- @LZX_VERSION@ -->
(The license terms are the CPL open source license. The copy in the depot is here.)
- Any file that uses C-style comments, such as javascript, must include the Laszlo Systems copyright at the top of the page, as shown here.
/* J_LZ_COPYRIGHT_BEGIN ******************************************************* * Copyright 2001-2005 Laszlo Systems, Inc. All Rights Reserved. * * Use is subject to license terms. * * J_LZ_COPYRIGHT_END *********************************************************/
- Always use explicit this.varname or parent.varname
- Convention for wrapping multiple classes/views/methods that are related
- Usually one class per file, with filename same as classname - Small related classes/instances should be encapsulated in the same file as appropriate
- Class/view code layout order:
1. datapaths
2. attributes
3. animators
4. methods
5. views
- Methods should generally declare CDATA in method nodes
<class name="foo">
<method name="doSomething"> <![CDATA[
// Javascript code here
]]>
</method>
</class>
Indentation
- Code should use the 1TB or "One True Brace Style" (originally part of K&R style). It keeps the first opening brace on the same line as control statement, indents the statements within the braces, and puts the closing brace on the same indentation level as the control statement (on a line of its own), as shown here.
while (x == y) {
something();
somethingelse();
}
finalthing();
For emacs users, the indent style can be defined:
(defconst lzx-c-style
'(
(c-basic-offset . 2)
(c-comment-only-line-offset . (0 . 0))
(c-offsets-alist . ((statement-block-intro . +)
(knr-argdecl-intro . 5)
(substatement-open . 0)
(label . 0)
(case-label . +)
(statement-case-open . +)
(statement-cont . +)
(arglist-intro . + )
(arglist-cont . 0)
(arglist-close . c-lineup-arglist)
))
(c-cleanup-list . (brace-else-brace scope-operator))
(c-hanging-comment-starter-p . nil)
(c-comment-continuation-stars . "* ")
(c-hanging-comment-ender-p . nil)
(c-echo-syntactic-information-p . t)
)
"Laszlo Programming Style")
(defun my-c-mode-common-hook ()
(c-add-style "LZX" lzx-c-style t)
(setq tab-width 8
indent-tabs-mode nil)
)
(add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
(autoload 'javascript-mode "javascript-mode" "Major mode to edit JavaScript files." t)
(add-to-list 'auto-mode-alist '("\\.js\\'" . javascript-mode))
(add-to-list 'auto-mode-alist '("\\.as\\'" . javascript-mode))
(add-to-list 'auto-mode-alist '("\\.lzs\\'" . javascript-mode))
The above code defines an indent style for all C-like languages, javascript being one, and what is used in LZX script.
Whitespace
- There are several indentation styles in the existing code. When making a change, do not make wholesale whitespace or layout changes at the same time you make algorithmic changes. It is best to follow the existing layout of a file when making algorithmic changes so that people reviewing or delving into the history of a file with can see the changes clearly. If you feel you must relayout a file, do so without any algorithmic changes and mark the change as being whitespace only.
Comments
- Comment definition style: e.g., <!- - comment - - >, javadoc style, /* */ and //
Documentation
- LZX files (such as those in components) can be commented with XML doc comments that precede each class and attribute definition. These comments are then pulled out via Laszlo doc tools and create the basis for the Laszlo documentation. Doc comments must begin with three (or more) '-' characters.
- Every file has
- filename, copyright text
- a description if it contains multiple classes
- Every class has:
- description
- description
- Every attribute and method has a comment:
- public
- description
- @param type name: description
- @return type: description (if there is a return value)
- private attributes start with _ and have a comment:
- @keywords private
- description
- declared events don't need a description if they just go with a declared attribute, and are declared private
- public
- Every file has
For example:
<class name="myclass">
<!--- This is an attribute comment. -->
<attribute name="myattr" value="default" type="string"/>
<!--- @keywords private readonly -->
<attribute name="secret" required="true" />
<!--- This is a method comment.
@param Number x: first number
@param Number y: second number
@return Number: the sum -->
<method name="mymethod" params="x, y">return x+y</method>
<!--- @keywords private -->
<attribute name="privateattr"/>
<!--- @keywords private -->
<method name="privatemethod">return</method>
</class>
