A guide to keep your code clean and up-to-date
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.
Inspite of Cotonti currently works with PHP 5.3.18 and higher we reccommend to use PHP 5.4 / 5.5 / 5.6 as more robust, strict and modern.
For MySQL versions we rely on 5.x as basement.
We strongly recommend using some IDEs or specialized Editrors instead of notepad, because it saves 30% of developer's time and helps to avoid simple mistakes. More over you can configure it to utilize Cotonti Coding Standards.
Many of modern developments software (even lightweight) provide plugin infrastructure, and can afford a lot of useful features:
Solid project environment with remote server support.
Projects managment with task focused interface.
Syntax highlight, real-time syntax checking, auto-complete, code hints and more.
Support for Version control systems, like GIT, to efficient workflow with Cotonti master repository or your own.
Now, we can not reccomend one of it, but can recommend to check these and choose best for yourself:
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 Cotonti built-in function cot_import() for input data filtration.
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 version control:
Update (git pull) your local copy before you start your work on changes, otherwise you may encounter problems when trying to push your changes.
Be careful. Test your changes before committing them. It will save you a lot of headaches.
Commit often. It's better to commit your changes in small steps, separating them over multiple commits. Then git push when you're done.
Write a clear comment for every commit, so everyone knows what exactly you have done. The commit command is git commit -m 'Fixed #123 small bug concerning xyz' (refer to an issue number and include a short description).
Tag stable milestones. At the very least, each version you'll release for public download must have a tag. The command for creating a tag is git tag -a v1.0 -m 'Version 1.0' (change the version number accordingly). To push a tag to Github you must use git push --tags.
For more information about how to work with git, read the simple git guide.
do you have architecture diagram for the frame work and refference guide. say for example if I want to quiery in database do I need to do it as regular php or is there any functions to get the results as array, same how about form validation ?
Toplam: 5, on page: 5
IMO, good idea is to explain WHY, not what it does...