Update:Archive/2.0/Developers/Best Practices

From MozillaWiki
Jump to: navigation, search

« Back to Archive | Update: Main

Ambox outdated.png THIS PAGE MAY BE OUTDATED
This article is in parts, or in its entirety, outdated. Hence, the information presented on this page may be incorrect, and should be treated with due caution until this flag has been lifted. Help by editing the article, or discuss its contents on the talk page.

Introduction

The purpose of this section is to define code style and methodology to ensure consistency throughout the project.

Formatting

Coding standards should be chosen, not argued about.

We have the responsibility to ensure consistency across the project, which is the primary goal behind establishing a set of guidelines for development.

Not many PHP projects have been undertaken under the Mozilla umbrella. There is no precedent for PHP, so it is in our best interests to choose a widely accepted standard for PHP programming.

By choosing a widely accepted PHP standard, we take a step in the right direction regarding readability, extensibility, ease of development, etc. Most people in the PHP community will be familiar with the syntax, making future developers feel 'at home' when they jump on board.

With the understanding that the Mozilla style guide (which is an interim guide and "not set in stone") recommends 2-space indentation (and items such as a modeline for EMACS), it is still in the best interests of the project to choose the PEAR Coding Standards as our primary style guide.

An additional constraint is the need for an 80 column limit on line length.

Coding Methods

Do

  • Stop programming and ask the group if you aren't sure about something.
  • Create functions for anything you will do more than once.
  • Create comment blocks before functions in phpDoc format.
  • Create meaningful to-the-point inline comments when necessary.
  • Clean and validate all inputs to prevent SQL injection or malignant HTML.
  • Use meaningful variable and function names.
  • Use <?php ?> to designate code blocks
  • Use CSS for all styles.
  • Write in XHTML ?
  • Create validated markup according to html 4.01 Strict.
  • Use $_REQUEST if input could come from GET or POST
  • Check data to make sure it is the right type. If you're expecting an int, make sure it's an int.

Don't

  • Do what you have always done "just because".
  • Create functions that do not return anything and echo/print HTML.
  • Use variable or function names that are ambiguous (like $var or validate()).
  • Create unnecessary functions.
  • Use <? ?> to designate a PHP block.
  • Use $array[foo] or $array["foo"] unless it is appropriate (constant or a variable catted with a string).
  • Loop MySQL queries.
  • Use variables from outside PHP (GET, POST, COOKIE...) in MySQL queries without cleaning them.
  • "Clean" above variables in place: $_GET['foo']=db_escape($_GET['foo']) is bad. $foo_dbescaped=db_escape($_GET['foo']) is OK.
  • Build URLs including Session ID (SID should be "automagically" added by PHP if we're using a no-cookie configuration).
  • Use inline styles. Ever.
  • Use <table> for design
  • Duplicate DOM IDs.
  • Use $_GET and $_POST with extra checks if the input could come from either GET or POST

Proposals

What do you think if

  • We prefix all our global identifiers (functions and variables those which are not class members) with mozupd_, to avoid namespace conflicts with libraries and includes? example: mozupd_addRating() or $mozupd_currentUser
  • We prefix all the functions in a module (include) that are not meant to be called from an including file (private utility functions) with _mozupd_? example _mozupd_dbTest()
Personally, if you want to avoid namespace conflicts, then you should be writing things as classes; so mozupd_addRating() becomes $rating = new Rating(); $rating->addRating();. I would tend to agree on "internal" methods being called _methodName but I think prefixing everything with mozupd_ etc. is going to get extremely annoying very quickly. --Csogilvie 10:55, 22 Jan 2005 (PST)

Why not use "umo_" instead? It's much more intuitive to use. --Topal 15:13, 16 Apr 2005 (PDT)

If we use classes then there's no need to worry about that. In the cases that there is a chance, simply do something like mozupdate_sendMail() --artooro 17:42, 22 Apr 2005 (EDT)

Database Calls

Please edit this as needed.

Database calls should be in the file /foo/bar.php To execute the query and get the results, you should use a wrapper of the form: db_Something(arg1,arg2,arg3)