manSavane - Cookbook: recipe #122, Coding Style

 
 
Show feedback again

recipe #122: Coding Style

To keep something easily readable and consistent, coders have to follow the same coding style.

Currently we only have a few rules, inspired by GNU Coding Standards.

Please respect them.

User Input Sanitization

Read recipe #259 (very important).

Indentation

Keeping the brackets on a same column

Comments

Use # as comment character, to have something uniform with all scripts, shell
Perl and PHP.

Use easily 'grepable' tags in the comments like DEPRECATED: or FIXME:

PHP/HTML Mixture

Do not mix different languages. It means that <?php ?> can occur only
one time in a file. If you need to print some HTML, use print();

HTML Layout

Look at others pages, try to mimic them. Usually, important headers should come with a <h3>, paragraph should be into <p>.

It is important to note that "paragraphs" means text that will be in align justify mode. Most texts should be in paragraph, but not short strings (lists etc).

If you are not sure, send a mail to savane-dev.

PHP Requires

Use only double-quotes for require statements

Feedback

It is important to provide feedback anytime user perform an action. It should be done using fb() (alias: utils_feedback())

For error messages should, the second argument of this function must be set to 1, something like:

Providing help about specific words could be something nice to. It can be done using help() (alias: utils_help()).

Gettext Support

Savane being internationalized, do not insert strings without call to the gettext _() function. And do not insert html tags inside (use printf/sprintf if you need to put variables inside the gettext function). If you want to print numbers, please use ngettext() function instead of thee simple _() function.

If you need to make the meaning of a string clear, so that translators know how to translate that word/sentence, you are encouraged to use the special comment tag "I18N". Any comment marked this way will be included in the savane.pot file for easy lookup.

Example:

Please see also the README in the po/ directory for some important considerations.

Please, always use format_date() to print dates. If you need them to be very short use format_date("minimal), if you want to put them in big tables, use format_date("short"), otherwise keep the first argument of format_date() unset.

Javascript

We cannot assume that all users have javascript support activated. So the policy is that javascript must never be mandatory to perform some action. But javascript may be a plus to make the layout more user-convenient.

Last update: Tue 28 Nov 2006 08:38:23 AM UTC

 

 

 

 

 

Audience and Context

Audience:
   Anonymous Users, Logged-in Users, All Project Members
Feature:
   Source Code Manager: Subversion Repositories
Action:
   Browsing
Show feedback again

Back to the top


Powered by Savane 3.1-cleanup