Skip to content
This repository was archived by the owner on Aug 23, 2019. It is now read-only.

Developer Guidelines

Jump to bottom
dalers edited this page Sep 24, 2012 · 11 revisions

Table of Contents

General

  • A Developer is a member of the Achievo community who submits work to the project. Work includes code (PHP, HTML, and CSS), images and documentation (either as part of the code, or project wiki pages).
  • A Project Maintainer is a developer who has write access to the project repository (and can merge submitted changes).
  • All developers have an obligation to read, understand and comply with the project's stated License Terms and Trademark and Logo Policy.

Design Principles

Don't Call Us, We'll Call You

The ATK Framework adheres to the paradigm of Inversion of Control, also called Dependency Injection or the Hollywood Principle. 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 module classes to get things done. ATK knows when a form needs to be presented, so it calls the module 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 ATK Framework documentation to become familiar with Achievo implementation.

Code Minimization

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). The ATK Framework takes care of all the standard work in an application such as security, form building, session handling, templating...

Assumption Driven Development

To be able to minimize code, the ATK Framework 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 for rapid application development with the ATK Framework, if you don't tell ATK 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 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. For more information, see the Hooks article in the ibuildings Achievo/ATK wiki for a list of methods that can be used to influence ATK's behavior.

Coding Guidelines

Code Formatting

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.

Class Naming

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")

PHPDoc Documentation

Achievo and the ATK Framework are extensively self-documentated using PHPDoc-format comments. Many IDEs (Integrated Development Environments), such as NetBeans, Eclipse and PhpStorm, can display PHPDoc-format documentation in convenient "pop-ups" for hinting when coding with ATK Framework API functions, or when searched for directly.

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, writing the PHPDoc documentation first (the Requirements), and then the code that implements it.

File Header 

 /**
  * @package atk
  * @subpackage ... 
  */

Inline Comments

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() ).

Configuration Variables

Configuration variables that are not specific to a module are defined in config.inc.php (e.g. database connection, security, etc.).

Module-specific configurations are defined in a configs/modulename.inc.php file (note that if a variable is defined in both a modulename.inc.php and config.inc.php, modulename.inc.php takes precedence). All configuration variables available in a module should be defined in a modulename.inc.php file, and with a complete explanation of both use and behavior.

Development Workflow

Achievo development uses the Git Distributed Version Control System (DVCS). The canonical project repository is hosted on GitHub in the atkphpframework group, and 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 (note that the blog post is a work in process though).

Here are other workflow guidelines:

  • All changes must be submitted via a Pull Request from a personal fork on GitHub, including changes from Project Maintainers. All submitted changes are reviewed by a project maintainer before being merged into the project repository. If the changes are submitted by a project maintainer, then a different project maintainer should respond to the pull request.
  • Before submitting a change, consider whether it is (or will be) of general interest and serve the greater good of the community. If the change is specific to your own personal interests or site implementation, it is not likely suitable to be included in the project. However, the advantage of using Git (and GitHub) is that you can still maintain changes for yourself within Git - just not push them back upstream.
  • It is preferred to identify a bug or defect in an Issue first, then correct the issue (with a Pull Request) with the issue referenced in the commit message and Pull Request. This helps keep the issue tracker a useful resource for finding if an issue has been fixed, and also provides an opportunity to discuss the issue, its cause and potential solution, and show who is working on the solution (which avoids multiple people from working on the same issue). If you find a bug and fix it, please take an extra moment to create an issue, and then submit your fix.
  • 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 for the benefit of other developers, preferably in advance so that everyone has the opportunity to review, comment and accept the new concepts. There are a number of places where you can do this, including in a commit message, the Pull Request description, in-line code comments, in an Issue, in a forum post, in a wiki page, etc. Consider the best location based on the complexity of the concept, and include references to the explanation in the other sources (e.g. write a forum post and then reference it in the Pull Request description). In general, the more complex the concept the more information should be provided, and the more advance notice should be given.

Clone this wiki locally