Code Organization Conventions

This page will walk yuo through the different decisions that were made for code organization when creating this project.

Code modularity

In the version the adaptation has been developed with, the BGA framework revolves around a few very monolithic files. This in not really keeping up with the good practices in code or project development, where the idea is to create small files that usually regroup a few methods or functions achieving related goals. As such, this project is trying to avoid those monolithic files and to take advantage of features of both PHP and JavaScript to allow for modularity in the source code.

PHP

On the PHP side, modularity is mostly accomplished using traits that are later imported in the progressevolutiontechnologyswh.game.php or progressevolutiontechnologyswh.action.php files. Some classes were also created to represent some of the game assets (namely cards and tokens). All those files are organized under the /modules/php directory.

In order to avoid relying on multiple require calls to include the relevant files in parts of the project, class loading is done trough a classmap autoloader. A classmap autoloader offers a better performance over a standard PSR-4-compliant autoloader. The autoloader function is then registered in the autoloading queue, allowing use statements to import classes in the files they are needed.

JavaScript

On the JavaScript side, modularity is accomplished by taking advantage of the AMD loader provided by the dojo toolkit. Unfortunately, most IDEs won’t allow for code completion and analysis. This has the advantage of leveraging the toolkit the BGA framework already uses for the JavaScript code.

All the created files are organized under the /modules/js directory.

Code documentation

Most of the code documentation happen directly in the source files, and an online version is available in the API part of this website (see the left sidebar).

Some of the most complex algorithm (compared to the majority of the project) have dedicated pages in the Algorithms part of this documentation.

PHP

PHP source files are documented using PHPDoc DocBlocks comments and tags.

The online version has been created using the phpdoc-to-rst project, resulting files being slightly amended for readability.

JavaScript

Javascript source files are documented using JSDoc comments. A Sphinx extension is then used to document all the sources files using the JSDoc comments contents, and are amended as necessity dictates.

Visibility conventions

PHP

As a rule of thumb, unless a method or property is supposed to be accessed from outside to=he class it has been defined in, its visibility will be set to private.

As such, all utility methods (defined in the SwHawk\ProgressEvolutionOfTechnologySWH\Modules\Traits\Utility namespace) are private methods. On the other hand, methods in the SwHawk\ProgressEvolutionOfTechnologySWH\Modules\Traits\Actions, SwHawk\ProgressEvolutionOfTechnologySWH\Modules\Traits\FrontEndActions and SwHawk\ProgressEvolutionOfTechnologySWH\Modules\Traits\States namespaces are supposed to be invoked from other classes and files in the framework so their visibility must be public.

Javascript

JavaScript as a language has not concept of defining method or property visibility. As such, a workaround has been found by defining “private” methods by defining them in the function body of each AMD module, and not to be returned with the class declared by the dojo.declare() method.