-
Notifications
You must be signed in to change notification settings - Fork 18
Developer Guidelines
The ATK Framework adheres to the paradigm of Inversion of Control, also called Dependency Injection or the HollywoodPrinciple. This means that the main application flow is not determined by Achievo, or by you as the developer of an Achievo module, but by ATK itself. To do its work, ATK calls methods in your classes to get things done. ATK knows when a form needs to be presented, so it calls Achievo essentially saying "I'm going to present a form; give me the fields you want to have in the form".
Study Achievo code and review the ATK Framework documentation to become familiar with the ATK Framework, in particular the Hooks article in the ibuildings Achievo/ATK wiki for a list of methods that can be used to influence the behavior of the ATK Framework.
We are lazy developers. This means we don't like to write too much code. ATK is completely focused on getting as much done as possible, using as few lines of code as possible. So instead of giving you many objects that can do an enormous amount of things for you, we have a very minimal API that does things that you might expect from a CRUD application, because in the end, most applications work more or less the same. This means that we do not only abstract features, we abstract the whole concept of an application. This is why we can have the slogan 'an application in 10 lines of code'. You only code what makes your app different from other apps. (In other words, you can focus on your business logic). Security, form building, session handling, templating; all of that is 'been there, done that' for most developers anyway, so ATK takes care of all of this for you.
To be able to minimize code, ATK adheres to what we call 'assumption driven development'. We assume a lot. We assume that when you build a CRUD application, you want to have a list of records with edit and delete buttons. We assume that if you make a field unique that you'll want to let the user know if he violates this, we'll assume that you'll want a calendar when you edit a date field. Or even for small internal details. Like "I'm assuming that if you want to hide a field for the user, that we can leave it out in the query that retrieves your record".
ATK basically says "look, I'm going to assume you'll want to have things this way; tell me if you want things otherwise". This principle makes ATK very Rapid, because if you don't tell it to change its assumptions, it will assume things in such a way that it can build an app for you.
ATK provides an enormous amount of Hooks that you can implement to change its behaviour. The hooks follow the Hollywood Principle, so if they're not there it's fine, but if they're there, ATK will call your hooks and you'll be able to influence its behaviour.
Achievo and the ATK Framework adhere to the following formatting rules:
- code is indented 2 spaces per level
- tab characters are not to be used (set your editor to "Expand Tabs to Spaces")
- parentheses used to delimit a code block are placed as follows:
function atkGroupByFilter($name, $groupbystmt, $flags=0)
{
$this->m_groupbystmt = $groupbystmt;
$this->atkFilter($name, $flags);
}
- if possible, keep lines under 80 characters by wrapping them intelligently.
Achievo and ATK were originally developed using the 'atkClassName' naming convention. In 2009, iBuildings embarked on integrating ATK with the Zend Framework and currently Achievo and ATK follow the Zend Framework naming conventions for classes, except:
- ATK classes follow the 'atkClassName' convention, and
- nodes are considered business entities, and are named using lowercase common English words (e.g., "class employee extends atkMetaNode")
/** * @package atk * @subpackage ... */Single line comments shall use "//" syntax.
// this is the correct syntax for a single-line comment /* this syntax should not be used for a single-line comment */Although the /* ...*/ comment syntax is valid, it makes it very hard to comment out large lines of code when debugging due to the intended comment block stopping on each comment line (which means either having to comment out small blocks, using die(), or sending the data to error_log() ). Achievo development uses the Git Distributed Version Control System (DVCS), and the canonical project repository is hosted on GitHub in the atkphpframework group. The development workflow follows the Fork and Pull model. Until the workflow is documented in the project wiki, refer to this blog post for more information (please note the blog post is a work in process though). Here are a number of general workflow guidelines for developers:
- Give useful information in Git commits and Pull Requests (meaningful to someone else!). It is obvious from the Git commit history which files have been changed, but it is not obvious why they were changed. The title and description of a Pull Request needs to inform the reader a) why the change was necessary and b) the general scope of the change including the effect on use and future development. If this is difficult to explain because some changes are unrelated to each other, then consider too much is being done in the commit or Pull Request, and the work should be divided into smaller units. Consider that the commit history needs to tell a story that developers who come after you can easily (and correctly) understand.
- Explain new concepts, preferably in advance so that other developers have the opportunity to comment and, more importantly, accept. There are a number of places where you can do this, including the commit message, the Pull Request description, in-line comments in the code, in a new Issue, a forum post, a wiki page, etc. Consider the best location based on the complexity of the concept, and include references to it from other places (e.g. write a forum post and reference it in the GitHub Pull Request description). In general, the more complex the concept, the more information should be provided, and the more advance notice needs to be given.
- Consider whether your change is of general interest, or is specific to your personal interests or site implementation. Changes which other developers will have to modify for their own sites are likely not suitable for submiting to the project.
Developers should strive to include documentation in their modules following the examples in Achievo and the ATK Framework. It may help to follow a Requirements Driven Development model, and write the PHPDoc documentation first, then the code to implement it.
/** * @package atk * @subpackage ... */
Single line comments shall use "//" syntax.
/* this syntax should not be used for a single-line comment */
Although the /* ...*/ comment syntax is valid, it makes it very hard to comment out large lines of code when debugging due to the intended comment block stopping on each comment line (which means either having to comment out small blocks, using die(), or sending the data to error_log() ).
Achievo development uses the Git Distributed Version Control System (DVCS), and the canonical project repository is hosted on GitHub in the atkphpframework group. The development workflow follows the Fork and Pull model. Until the workflow is documented in the project wiki, refer to this blog post for more information (please note the blog post is a work in process though).
Here are a number of general workflow guidelines for developers:
- Give useful information in Git commits and Pull Requests (meaningful to someone else!). It is obvious from the Git commit history which files have been changed, but it is not obvious why they were changed. The title and description of a Pull Request needs to inform the reader a) why the change was necessary and b) the general scope of the change including the effect on use and future development. If this is difficult to explain because some changes are unrelated to each other, then consider too much is being done in the commit or Pull Request, and the work should be divided into smaller units. Consider that the commit history needs to tell a story that developers who come after you can easily (and correctly) understand.
- Explain new concepts, preferably in advance so that other developers have the opportunity to comment and, more importantly, accept. There are a number of places where you can do this, including the commit message, the Pull Request description, in-line comments in the code, in a new Issue, a forum post, a wiki page, etc. Consider the best location based on the complexity of the concept, and include references to it from other places (e.g. write a forum post and reference it in the GitHub Pull Request description). In general, the more complex the concept, the more information should be provided, and the more advance notice needs to be given.
- Consider whether your change is of general interest, or is specific to your personal interests or site implementation. Changes which other developers will have to modify for their own sites are likely not suitable for submiting to the project.