As an Open-Source software, CartoWeb needs to be written following some coding guidelines and/or rules. It is the required condition unless the developpers community isn't able to share new features and enhancements.
Some of those advises may seem obvious, others less. For all, it is principaly a good way to produce more readable, maintainable and portable code.
It is highly recommended to be avoid absolute paths as much as possible. CartoClient and CartoServer may be relocated with very minimal even none reconfiguration.
It should be possible to extract the archive, launch a script, edit few options, and be ready to use the application with the built-in data set (see test mapfile).
Developers should absolutely set the following variables to true in their config (on both client and server sides):
Warning
These parameters will be overrided by the
profile parameter (See Section 4.1, “Common client.ini and
server.ini Options”).
- showDevelMessages = true
- developerIniConfig = true
Code should produce no notices before any CVS commit. Code should pass all tests.
This also means that the developpers should add and run unit tests for every new feature they add.
Developers should use the PEAR coding standards as the coding style reference in CartoWeb, with some exceptions. Have a look at http://pear.php.net/manual/en/standards.php.
Following are briefly described some guidelines to respect.
Developers should respect some indentation conventions when writing PHP code in CartoWeb:
- 4 spaces indentations are recommended,
- the use of tabs for indentation is prohibited, use space instead (select the appropriate preferences in your favorite code editor if needed).
Control statements should have one space between the control keyword and opening parenthesis.
It is also recommended to use curly braces even when they are optional.
This is correct:
if (condition) {
...
}
Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon.
This is correct:
$var = foo($bar, $baz, $quux);
Function declarations follow the "one true brace" convention.
Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.
Modifiers keywords (public, protected, private) are mandatory in class members and methods definitions. It is recommended to use private for most members and properties. Use public only for methods that needs to be accessible from outside the class.
In coreplugins or plugins classes, it is generally better to use protected instead of private since most methods may have to be redeclared in extended classes (projects plugins). Then only use private for members/properties you do not want to be redeclared.
Avoid deep blocks nesting:
This is correct:
for ($i = 0; $i < 10; i++) {
if (! something ($i))
continue;
doMore();
}
Classes should be given descriptive names that should always begin with an uppercase letter. Avoid using abbreviations.
Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps").
function handleKeymapTool()
Functions and methods names should always describe actions.
Developpers should declare the access modifiers (public, private, protected) for each function or method.
To improve php code and object structure readability, automatic code documentation is implemented in CartoWeb. It is based on specific comments describing classes, methods, interfaces and objects. See Chapter 8, Code Documentation for more information.
In CartoWeb, mainly for the templates, HTML coding should respect some rules.
To take benefits of recent browsers enhancements and, above all, to make HTML codes easier to read and maintain, some HTML-coding guidelines should be followed.
- for indentation : preferably use 2 white spaces (such an indentation might be used for javascript coding as well).
- Generated HTML pages should be XHTML 1.0 (say Transitional for now) valid and pass matching W3C validation: http://validator.w3.org/
XHTML (standing for eXtensible Hypertext Markup Language) was chosen vs simple HTML for following reasons:
- XHTML is aimed to replace HTML
- XHTML is a stricter and cleaner version of HTML
- XHTML is HTML defined as an XML application
For more information on XHTML, reference and tutorial are available here : http://www.w3schools.com/xhtml/ Specially useful pages are:
- Differences between HTML and XHTML: http://www.w3schools.com/xhtml/xhtml_html.asp
- XHTML syntax: http://www.w3schools.com/xhtml/xhtml_syntax.asp
But, here are some things people must know to get XHTML valid generated pages.
In HTML some elements can be improperly nested within each other like this:
<b><i>This text is bold and italic</b></i>
In XHTML all elements must be properly nested within each other like this:
<b><i>This text is bold and italic</i></b>
All XHTML elements must be nested within the <html> root element. All other elements can have sub (children) elements. Sub elements must be in pairs and correctly nested within their parent element. The basic document structure is:
<html> <head> ... </head> <body> ... </body> </html>
This is because XHTML documents are XML applications. XML is case-sensitive. Tags like <br> and <BR> are interpreted as different tags.
This is wrong:
<BODY> <P>This is a paragraph</P> </BODY>
This is correct:
<body> <p>This is a paragraph</p> </body>
This is wrong:
<table WIDTH="100%">
This is correct:
<table width="100%">
Non-empty elements must have an end tag.
This is wrong:
<p>This is a paragraph <p>This is another paragraph
This is correct:
<p>This is a paragraph</p> <p>This is another paragraph</p>
Empty elements must either have an end tag or the start tag must end with />
This is wrong:
This is a break<br> Here comes a horizontal rule:<hr> Here's an image <img src="happy.gif" alt="Happy face">
This is correct:
This is a break<br /> Here comes a horizontal rule:<hr /> Here's an image <img src="happy.gif" alt="Happy face" />
IMPORTANT Compatibility Note:
To make your XHTML compatible with older browsers, you should add an extra space before the "/" symbol like this: <br />, and this: <hr />.
This is wrong:
<dl compact> <input checked> <input readonly> <input disabled> <option selected> <frame noresize>
This is correct:
<dl compact="compact"> <input checked="checked" /> <input readonly="readonly" /> <input disabled="disabled" /> <option selected="selected" /> <frame noresize="noresize" />
Here is a list of the minimized attributes in HTML and how they should be written in XHTML:
<dl compact="compact"> <input checked="checked" /> <input readonly="readonly" /> <input disabled="disabled" /> <option selected="selected" /> <frame noresize="noresize" />
HTML 4.01 defines a name attribute for the elements a, applet, frame, iframe, img, and map. In XHTML the name attribute is deprecated. Use id instead.
This is wrong:
<img src="picture.gif" name="picture1" />
This is correct:
<img src="picture.gif" id="picture1" />
Note: To interoperate with older browsers for a while, you should use both name and id, with identical attribute values, like this:
<img src="picture.gif" id="picture1" name="picture1" />
IMPORTANT Compatibility Note:
To make your XHTML compatible with today's browsers, you should add an extra space before the "/" symbol.
"alt" attribute is mandatory for <img /> tag in XHTML. But it can - and sometimes should - have a void value. "alt" is used to specify a replacement text when image is not loaded (image unavailable, not yet loaded or user deactivated images...). For "data" images, a convenient alternative text should be specified but for layout-only pictos it is no use to display a replacement message.
For instance:
<img src="mainmap.gif" width="400" height="200" alt="Main map" /> <img src="pixel.gif" width="50px" height="1px" alt="" />
