This document contains basic recommendations and requirements for Cotonti developers. It helps different people with different habits and insights develop a quality and rock-solid product as the result of their collaboration.
PHP and MySQL versions should be both 5.x, as we rely on 5.x as basement.
We strongly recommend using specialized IDEs instead of notepad, because it saves 30% of developer's time and helps to avoid simple mistakes. Our current IDE of choice is “NetBeans for PHP” for the following reasons:
Solid project environment with remote server support.
Syntax highlight, real-time syntax checking, auto-complete, code hints and more.
Superior built-in Subversion (SVN) support, which merges changes automatically and resolves conflicts much better than TurtoiseSVN.
A modern cross-platform “all-in-one” development tool which is more lightweight than Eclipse.
When you write some code, think it over if it could be reused somewhere. All reusable code is better when it can be called as functions instead of copy&paste approach. So, write reusable and generic code whenever possible. Put your functions into include files and provide the API documentation, so it is clear for the others how to use them.
Keep the logic separate from view. For example, if you want to provide functions to retrieve some data from the database, process it and render in the template, you would better have 2 function rather than one: 1st to get and process data resulting into some variable and 2nd to render the layout. It's not always working, but try to follow it in most cases.
Do not put HTML and natural language literals into your code. Use internationalization (language files) and resource strings or templates itself. It may be time-consuming when you first implement it, but will save a lot when it comes to modifications.
Comments and a clear API reference saves a lot of time for others to understand and use your code as well as following Code Style Guide.
It is a common statement that good code documents itself, but still some comments are needed not to get lost in hundreds of lines going non-stop. So, comment logical parts and major steps in your code. Do not explain obvious things, but explain things which are implicit or depend on external context.
In Cotonti we use PHPDoc style comments to get good API documentation out of the box without spending much time on it. Please read http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html to get familiar with it and use it in your code. Note that NetBeans, Eclipse PDT, Zend IDE and some other IDEs have built-in support for phpDoc commenents.
Here are some basic things to remember when writing code:
Import and filter variables before you use it in code. Use isset() and empty() checks. Use is_null() to detect whether a variable was sent at all or not.
Make sure all variables are filtered with $db->quote()/$db->prep() or typecasted to int before you use them in SQL queries. Alternatively, use placeholders to embed variables in queries.
Do not put imported variables into include file names.
Do not use register_globals in PHP, do not use $_GET, $_POST and $_COOKIE explicitly.
Use SQL abstraction layer instead of direct mysql_ calls.
Use single quotes instead of double quotes in strings without variable interpolation required.
Do not put integers in 'quotes' in SQL quires. This way you apply string algorithms on them instead of numeric, which may result into 10-40% performance loss for certain queries.
A few things to remember when using Subversion:
Update your local copy before you start your work on changes, otherwise you may roll back changes made by others.
Be careful. Sometimes it is better to implement changes on your local folder and test it, before you apply changes on SVN repository.
Write comments for Commits, so everyone knows what exactly you have done.
Tag stable milestones.
yup, but dont get too excited with comments in code, like putting comments on every single line :p
IMO, good idea is to explain WHY, not what it does...