URL:
<http://gna.org/cookbook/?func=detailitem&item_id=122>
Summary/Question: Coding Style
Project: Savane
Submitted by: yeupou
Submitted on: vendredi 25.11.2005 à 11:36
Category: None
Importance: 3 - Normal
Status: Approved
Privacy: Public
Assigned to: None
Open/Closed: Open
_______________________________________________________
Details:
To keep something easily readable, coders have to follow a same coding style.
Currently we only have a few rules, inspired by GNU Coding Standards.
INDENTATION
-----------
Keeping the brackets on a same column
function ($var)
if (1 != 0)
{
print 'a';
}
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 occurs 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 into <p<.
If you are not sure, send a mail to savane-dev.
PHP REQUIRE
-----------
Use only double-quotes for require statements
require "../include/pre.php";
USER INPUT SANITIZATION
---------------------------
It is important to always obtain user input from sane_*() functions.
The goal is to get Savane working with register_globals set to off. Which
means all variables that can be provided as user input should not come as
global but always from sane_*() functions, like sane_post() or
sane_cookie().
Gradually pages will be register_globals off compliant. The ones that are
have a call to register_globals_off() after the beginning requires. It is
absolutely forbidden to remove such call. Pages that are made compliant with
register_globals set to off should stay that way.
FEEDBACK
----------------
Providing feedback on top of the page is the better way to return feedback to
user. It means that actions must fed the $feedback variable and ideally all
these actions should be done _before_ the page header function call.
Feedback messages should be more or less similar, you should use the function
fb() (aliases: utils_feedback(), feedback()):
fb(_("Bla bla bla"));
For error messages should, the second argument of this function should be set
to 1, something like:
fb(_("Bla failed due to crappy coding"), 1);
Providing help about specific words could be something nice to. It should be
used using help() (alias: utils_help())
help(_("My sentence with words unclear"),
array(
_("sentence")=>_("sentence is ...")
));
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:
# I18N
# This comment will be included in the potfile
print _("This is a sentence with a difficult meaning.");
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.
_______________________________________________________
Reply to this item at:
<http://gna.org/cookbook/?func=detailitem&item_id=122>
_______________________________________________
Message posté via/par Gna!
http://gna.org/
_______________________________________________
Savane-dev mailing list
[email protected]
https://mail.gna.org/listinfo/savane-dev
