Code quality with Magento

Bad code is hard to read, hard to adjust and even harder to hand over to other developers. This leads to considerable additional costs – for example when the development company changes. Dr. Nikolai Krambrock and Andreas von Studnitz, both experienced and certified Magento developers, talked about this issue at Meet Magento on 2014. Issues of their presentation: What is good source code? How does it look like? How is it produced? The first part of the presentation is about code quality in general. The second part is about code quality specific to Magento that helps developers to write better code in Magento.

Here are the corresponding PowerPoint slides to the presentation:
Code_Quality.pdf

What is code quality good for?

Customers are interested in external code quality: Functionality, usability, security, availability and reliability. Additionally, they want to extend and change their shop to acceptable costs. The external code quality is mainly determined by the internal code quality. Source code is of good internal quality if developers can easily read and change it. Not easy to read for machines but for humans.

General code quality

Guidelines for good code quality

Good internal and uncomplicated source code can be archived as long as developers follow some simple guidelines. Unfortunately, only the guidelines are simple – their compliance not at all. Writing simple source code is a lot harder than writing complicated source code.
Basic guidelines:

Easy solutions for problems are an essential precondition of good code quality. If you want to sort five elements then better write a bubble-sort instead of a complicated quick-sort. Recursions should also be avoided as long as it is possible to use for-loop instead.
Elements of structure – such as classes and methods – only make sense if they are used for structuring – so only if they are medium seize. Classes should have 100-200 Lines of Code, methods 3-20 Lines of Code.
After using if-conditions (if) or loops (while) the source code is going to be indented. More than three indentations are a sign for too complex code which needs to be revised. Above five indentations the source code has definitely to be revised.
Speaking names of variables are important because they are a big part of the source code’s documentation and they work as a kind of story. They let speak the code for itself. However, this only works with good names:
- Example for very bad naming: $c=Mage::getModel
- Example for bad but often used naming: $customer=getModel(„…“)
- Example for good naming: $customerToAdd=getModel(„…“)
- The same holds true for speaking methods and class-names. For instance: „deepClone()“
  says more about the process than „copy()“
Dead Code is source code that is code which is never executed. It can be found by static analyses and should be deleted.
According to Martin Fowler duplicated source code is a fatal internal problem of code quality. It should be transferred into functions, inheritances or collectively used classes.
Magic numbers are numbers or strings which appear in the middle of the source code – e.g. in „x>7“. Magic numbers should be transferred into constants, configurations or language files.

Tools of good code quality

The most important tool of software development is version management. It offers much benefit in comparison to almost no effort and costs. Version management saves all intermediated versions of every change and the software: Lost code can be retrieved; if a bug appears all the changes up to this bug can be examined.
Another important tool is automated testing. There are two variants: Black-Box tests and White-Box tests. Black-Box tests are testing the functionality of source code e.g. Selenium. White-Box tests are used with PHP Unit in the context of PHP. This way of testing is primarily helpful for big projects or for modules which has to work across a range of functions.

Encapsulation of modules

Magento-modules should have as little dependencies on other modules as possible:

- Modules should be independently executable and should have as little dependencies on other modules as possible – especially on external modules. The same is true for templates. Templates are project-related and always different. Therefore, they require repeated adaption as soon as they are dependent on modules. This is related to enormous effort which can be avoided by as little dependency as possible.
- It should be possible to disable single modules. By doing so it is easier to find the module that contains an error without destroying the template. Layout-updates ensure the disabling of the modules. For this purpose the work needs to be done in the theme base/default, not in project-related themes. By working in the theme base/default the modules are neither going to be overwritten nor adapted. Anyway, some projects only allow working in project-related themes. In this case a special module needs to be developed which contains the project’s name and which covers up the additional functions of the template.

Ability of updates

To keep Magento updateable you should not change the core (called core-hack), external files or any other Magento files. These changes are just overwritten by your next update. In the end the changes have to done again by hand – the result is often defective. Rewriters or observer should be used instead. The same holds true for language files of Magento. Create additional translation-files instead. Code pools help by doing so. They enhance the overwriting if functional adaptions have to be done – as long as they are used correctly:

local for project-specific modules
community for published/shared modules
core for core
lib for external libraries

Copying template-files and changing them can also bring problems while updating: You copy a layout.xml-file to change a line in there. At the same time you freeze the remaining unchanged files, so that these are kept retaining after the next update. Once again all changes of the update have to be redone. Possible solutions: Minimizing the copies of template-files and using local.xml-files or module-specific layout.xml-files.

Minimal changes of the source code

Important guideline to produce good code: “Only no code is good code. “ Therefore as few lines of source code as possible should be used. The best weapon to fight against much source code is to use existing Magento-functions instead of creating new ones. A good example for this are tier prices for individual options. Magento does not offer this function, though. A solution for this problem would be to generate additional costumer options for every single tier. A bad idea would be to overwrite the logic of the price.

Model View Controller in Magento

Magento implements the concept of Model-View-Controller (MCV) with some changes in the original concept. The most important separation in Magento is the one of code and template. Both are only partial compatible with MVC because the template as well as the blocks belongs to the View. Anyway, this separation is the most important element in Magento: In the template must not be a line-long source code and in the source code no HTML. This separation has to be observed. It also helps to accumulate files in modules, it helps to obtain the logic in controllers and observers and it helps to create help-functions for the template in blocks.

Changes via setup scripts

Setup scripts are important to improve the quality of projects and to attain more security in the business. Their advantage: If changes have to be done via set up scripts they only have to be done onetime. Thereby, direct changes of the database or of the admin are avoided. Changes in tables and columns of the database, attributes or configurations can also be done in the backend, but they carry the risk of being defective – especially while working on bigger projects with various systems and developers.

Modules of unknown providers

External modules cannot be avoided during most of the projects. To obtain code quality here as well it makes sense to use modules of known and reliable sources only. If the provider of the modules is not known a detailed code-analysis should be done. Modules of dubious provider, or modules with an own licensing-module or encrypted source code should not be used. In case of emergency the latter can prevent an access to the source code to correct mistakes.

Conclusion

Good code quality should be in both parties interest – the customer and the Magento agency. It promotes the comprehensibility as well as the maintainability of the source text and it reduces the probability of grave mistakes. Everyone who takes these guidelines into account will write easier source code and can attain better results.

Code quality with Magento

What is code quality good for?

General code quality

Guidelines for good code quality

Tools of good code quality