OXID Modul-Zertifizierung Bedingungen

Transcription

1 OXID Modul-Zertifizierung Bedingungen

2 Copyright Copyright 2012 OXID esales AG, Deutschland Die Vervielfältigung dieses Dokuments oder Teilen davon, insbesondere die Verwendung von Texten oder Textteilen bedarf der ausdrücklichen vorherigen Zustimmung der OXID esales AG. Eine Dekompilierung des Quellcodes, unerlaubte Vervielfältigung sowie die Weitergabe an Dritte ist nicht gestattet. Zuwiderhandlungen werden ausnahmslos zur Anzeige gebracht und strafrechtlich verfolgt. Die alleinigen Rechte an der Software sowie an diesem Dokument liegen ausschließlich bei der OXID esales AG. Die in diesem Dokument bereit gestellten Informationen wurden nach aktuellem Stand der Technik verfasst. Die OXID esales AG übernimmt jedoch keine Haftung oder Garantie für die Aktualität, Richtigkeit und Vollständigkeit der bereit gestellten Informationen. Da sich Fehler, trotz aller Bemühungen nie vollständig vermeiden lassen, sind wir für Hinweise jederzeit dankbar. Konventionen In diesem Dokument werden die folgenden typographischen Konventionen verwendet: Kursive Schrift wird für Dateinamen, Pfadangaben, -Adressen und URLs verwendet. Nichtproportionalschrift wird für Codebeispiele und Namen von Codeelementen verwendet. Nichtproportionalschrift kursiv wird für Navigationsschritte verwendet. Impressum OXID esales AG Bertoldstraße Freiburg Deutschland Fon: +49 (761) Fax: +49 (761) Vorstand: Roland Fesenmayr (Vorstandsvorsitzender), Eric Jankowfsky, Andrea Seeger Sitz: Freiburg Amtsgericht Freiburg i. Brg. HRB /10

3 Rules for OXID eshop Module Certification This list contains all conditions for developing certificable eshop modules for eshop versions above 4.0. The document contains all conditions for certification and shall provide a quick overview. Details to the single issues will be communicated in the offered trainings and are noted in the trainingsmaterials respectivly. Category Policy fullfilled? Softwaretests testclass per module class 1.2 Class Unit_MODULKLASSETest extends OxidTextCase 1.3 at least 1 test per method 1.4 demonstrative & destructive tests 1.5 NO asserttrue(true) 1.6 atomic tests 1.7 MODULNAMETest.php for automatic execution of all tests 1.8 code coverage > 90% 1.9 minimal disturbance of the eshop tests Softwarequality 2.1 no globals * 2.2 no global functions * 2.3 no business logic in smarty funktions 2.4 PHP5 Code 2.5 oxsupercfg 2.6 getter & setter 2.7 oxexceptions 2.8 maximum length of methods < 80 lines (< 40 Best Practice) * 2.9 maximum NPath complexity < 200 * 2.10 maximum cyclomatic complexity = 4 * 2.11 maximum C.R.A.P. index < 30 * intermodul compatibility 3.1 prefix before datenbase field names 3.2 prefix before table names 3.3 prefix before config parameters 3.4 prefix before language constants 3.5 ::parent call * 3.6 oxnew * 3/10

4 dokumentation 4.1 Readme.txt 4.2 Install.sql 4.3 Changelog.txt 4.4 PHPDoc ) 4.5 folder copy_this 4.6 folder change_full 4.7 folder Documentation 4.8 changes in templates marked by (MODULNAME BEGIN MODULNAME END) 4.9 good comments!!! (see example comments) * Variations could be allowed in justified cases. 1. Remarks to Softwaretests 1.1. Per modul class there should be a test class und each class should be stored in a separate file* 1.2. Naming conventions for test classes: Class Unit_MODULKLASSETest extends OxidTextCase and testmethods: testmethodename() so it is clear which testmethod tests which method 1.3. For each method there should be at least one test in the testmethod respectively. Hint: you should have NPath complexity number of tests in the testmethod 1.4. You should test for correct working of a method as well as for failure cases and for edge cases. (what happens on the edge of the domain?) What happens with correct input? What happens with incorrect input? What happens in edge case? 1.5. Do not test for conditions which are fullfilled anyway - NO asserttrue(true) 1.6. Each method should be tested on its own. There shouldn t be any dependencies between the tests. If there are use stubs and dependency injection. See PHPUnit Manual - Mocking 1.7. Write a main class MODULNAMETest.php to run all tests at once. Shop tests AND module tests should run together!!! As an example for MODULNAMETest.php see AlltTestsUnit.php 4/10

5 1.8. The code coverage has to be greater than 90%. This means the code coverage for Lines of Code (LOC) 1.9. Your unit tests should interfere as least as possible with the shop tests. If you run all tests at once (eshop-unittests + Modul-Unittests) no shop test should fail. 2. Remarks to the category software quality 2.1. Avoid the use of global variables Avoid the use of global functions Use smarty only for design purposes. Business logic belongs to the PHP-Level Do object orientated programming. 2.5.???oxSuperCfg um modulspezifische Parameter zu setzen und abzurufen ist die Klasse oxsupercfg abzuleiten (z. Bsp. speichern von Variablen in einer Session etc. ) 2.6. The access of public variables of class should be realised via getter and setter methods Use oxexception to derive from to create your own exception classes The number of lines of a method shouldn t be higher than 80*. Best practise is below 40. And we will reject modules containing methods with more than 120 lines of code The NPath complexity is the number of possible execution paths throug a method. Each control structure (e. g. if, elseif, for, while, case,...) is taken into account also the nested and multipart boolean expressions. It should be lower than 200 and module will not be certified if it is above The cyclomatic complexity is measured by the number of if, while, do, for,?:, catch, switch, case statements, and operators && and (plus one) in the body of a constructor, method, static initializer, or instance initializer. It is a measure of the minimum number of possible paths through the source and therefore the number of required tests. Generally 1-4 is considered good, 5-7 ok, 8-10 consider re-factoring, and 11+ re-factor now. A hard limit is a ccn of Change Risk Analysis and Predictions (C.R.A.P.) index of a function or method uses cyclomatic complexity and code coverage from automated tests to help estimate the effort and risk associated with maintaining legacy code. A CRAP index over 30 will not be accepted. 5/10

6 3. Remarks to the category intermodul compatibility General: The Prefix should be used consistently and it should be registered at Oxid. Therefore the prefix should be the first part of the name of your 3.1. data base field 3.2. data base table 3.3. config parameters 3.4. language constants 3.5. If you extend a method you should always call the parent method via parent::methoden name z 3.6. For creating objects always use the oxnew() function. 4. Remarks to the category documentation 4.1. in Readme.txt there should be the following informations : Title the name of the module Author the author/company of the module Prefix the prefix you use Version version of the module which is described Link a link to the homepage of the author/company Mail for contact Description a short description of the function of the module Extend which classes and methods are extended Installation a detailed description how to install the module Modules which other modules are used Libraries which libraries are used Resources other resources 6/10

7 Beispiel Readme.txt ==Title== Example module ==Author== Der Autor ==Prefix== pref ==Version== ==Link== link ==Mail== ==Description== A description ==Extend== *someclass --some method ==Installation== do something 4.2. A file which contains SQL statements to alter the data base should be named install.sql and has to be explained in the documentation 4.3. The file changelog.txt should have the following form: ==0.1.0== * Initial release of module. ==0.2.0== * some changes * some bugfixes 7/10

8 that means version numbers are surrounded by ==, where the newest number is on top of the file and each entry of a version starts with a * 4.4. optional: a html document which was created with PHPDoc using the comments of the source code 4.5. A folder copy_this which will be copied in the root directory of the shop -> see example file Ordnerstruktur.txt 4.6. A folder change_full which will be copied into the template directory -> see example file ordnerstruktur.txt 4.7. optional: a folder doc which contains the html documentation created with PHPDoc and further documentation -> see example file ordnerstruktur.txt 4.8. Changes in Templates should be marked to make more easy to find them. [{* MODULNAME BEGIN *}]... [{* MODULNAME END *}] 8/10

9 Example ordnerstruktur example/ +-- readme.txt +-- src +-- changed_full +-- out +-- azure +-- basic +-- Changelog.txt +-- copy_this +-- admin +-- core +-- modules +--Module +-- out +-- admin +-- de +-- en +-- tpl +-- views +-- docs (optional) +-- documentation.html +-- user_comments.php \-- Install.sql (optional) +-- tests +--ModulnameTest.php ( Testsuite ) +-- unit +-- modules +--Module ( put the test files here in ) 9/10

10 4.9. Good comments means that for each class variable, method and class you should write a comment. A comment should give additional information and not only repeat the name. (see example) example: <?php /** * Cupboard * Furniture $Revision$ Copyright (C) Somecompany. All rights reserved. GPL oxbaseclass */ class Cupboard extends Cupboard_parent { /** * Number of cups in the cupboard. Declared in units * int */ protected $numberofcups; /** * Take a cup from cupboard * * Reduces the amount of cups by the specified amount. If * there are not enough cups left the cupboard is emptied. The actual amount * of cups removed from the cupboard will be returned. * drink int $amount int */ public function take( $amount ) { // inline comment $this->numberofcups -= $amount = max( $this->numberofcups, $amount ); return $amount; } 10/10