< Internationalization

Unit Tests >

5. Code Convention

5.1. Introduction

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.

5.2. General Coding Rules

5.2.1. Paths

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.

5.2.2. Extract and Run Deployement

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).

5.2.3. Development Configuration

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

5.2.4. Unit Tests

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.

See Chapter 6, Unit Tests.

5.3. PHP

5.3.1. Coding Style

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.

5.3.1.1. Indent

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).

5.3.1.2. Control Structures

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) {
  ...
}

5.3.1.3. Function Calls

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);

5.3.1.4. Function Definitions

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.

5.3.1.5. Class Modifiers

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.

5.3.1.6. Nesting

Avoid deep blocks nesting:

This is correct:

for ($i = 0; $i < 10; i++) {
  if (! something ($i))
    continue;
  doMore();
}

5.3.1.7. PHP Code Tags

Always use

<?php ?>

to delimit PHP code, not the

<? ?>

shorthand.

5.3.1.8. Naming Conventions

5.3.1.8.1. Classes

Classes should be given descriptive names that should always begin with an uppercase letter. Avoid using abbreviations.

5.3.1.8.2. Functions and Methods

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.

5.3.1.8.3. Constants

Constants should always be all-uppercase, with underscores to seperate words.

5.3.2. Comments

5.3.2.1. Php Doc Comments

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 7, Code Documentation for more information.

5.3.2.2. Inline Comments

As often as necessary, the developers should add code comments to explain verbosly the purposes of commands.

5.4. HTML Coding Standards

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:

But, here are some things people must know to get XHTML valid generated pages.

5.4.1. Nesting

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>

5.4.2. Lower Case

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%">

5.4.3. Closing

5.4.3.1. All Elements

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>

5.4.3.2. Empty Elements

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 />.

5.4.4. Minimization

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" />

5.4.5. Id vs Name

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.

5.4.6. Image "alt"

"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="" />
valid xhtml 1.0 valid css