Web Development Standards Documentation Release Latest
Total Page：16
File Type：pdf, Size：1020Kb
Web Development Standards Documentation Release latest Mar 09, 2018 Contents 1 PHP Coding Guidelines 3 1.1 General considerations..........................................3 1.2 Namespace, Interface and Class names.................................3 1.3 Method names..............................................4 1.4 Variable names..............................................4 1.5 Filenames.................................................5 1.6 Constant names..............................................5 1.7 Control Structures............................................5 2 Laravel Guidelines 7 2.1 Getting Started..............................................7 2.2 Controllers................................................7 2.3 Models..................................................7 2.4 Table and field naming..........................................8 2.5 Adding tables, index or inserting sample data..............................8 2.6 Routes..................................................8 2.7 Blade and Views.............................................8 2.8 Unit Testing...............................................8 3 Javascript Guidelines 9 4 Frontend Guidelines 11 5 API Guidelines 13 i ii Web Development Standards Documentation, Release latest It is important for the Web Developers of Appetiser to have a common way of doing things when they work on projects. Coding Standards will address the issues of developers having different styles and approach and are an important factor in achieving high quality of code. Contents 1 Web Development Standards Documentation, Release latest 2 Contents CHAPTER 1 PHP Coding Guidelines This document defines technical and style guidelines on how to code in PHP when doing Appetiser projects. 1.1 General considerations • Follow the PSR-2 standard for code formatting • PHP files must contains exactly one class and does not output anything if it is called directly. Therefore you start your file with a <?php tag and must NOT end it with the closing ?>. • Every file must contain a header stating namespace • Most web and API projects of Appetiser are based on Laravel • PhpStorm will be the official IDE 1.2 Namespace, Interface and Class names • Only the characters a-z, A-Z and 0-9 are allowed for namespace and class names. • Namespaces are usually written in UpperCamelCase but variations are allowed for well established names and abbreviations. • Class names are always written in UpperCamelCase. • The main purpose of namespaces is categorization and ordering • Class names must be nouns, never adjectives. 3 Web Development Standards Documentation, Release latest 1.3 Method names All method names are written in lowerCamelCase. In order to avoid problems with different filesystems, only the characters a-z, A-Z and 0-9 are allowed for method names – don’t use special characters. Make method names descriptive, but keep them concise at the same time. Constructors must always be called __construct(), never use the class name as a method name. • myMethod() • someCoolMethodName() • betterWriteLongMethodNamesThanNamesNobodyUnderstands() • singLoudly() • __construct() 1.4 Variable names In the PHP world, there are lots of argument when it comes to variable naming conventions. Some uses a lowerCamelCase convention while others use snake_case but basically there is no clear rule on what to use. In Appetiser, we wll use all lowercase snake_case as the convention since variables in PHP are case sensitive thus an all lowercase snake_case convention is easier to use, prevents case errors and can be easily distinguishable from method and function names. Variable names should be: * self-explanatory * not shortened beyond recognition, but rather longer if it makes their meaning clearer The following example shows two variables with the same meaning but different naming. Correct naming of variables • $singleton_objects • $arguments_array • $turn_off_the_app Incorrect naming of variables • $sObjRgstry • $arg_Arr • $cxny • $a $b $c If variables are expected to contain boolean data it must start with ‘‘is‘‘ , ‘‘has‘‘ or ‘‘can‘‘ • $is_admin • $can_delete • $has_payment As a special exception you may use variable names like $i, $j and $k for numeric indexes in for loops if it’s clear what they mean on the first sight. But even then you should want to avoid them. 4 Chapter 1. PHP Coding Guidelines Web Development Standards Documentation, Release latest 1.5 Filenames These are the rules for naming files: • All filenames are UpperCamelCase. • Class and interface files are named according to the class or interface they represent • Each file must contain only one class or interface • Names of files containing code for unit tests must be the same as the class which is tested, appended with “Test.php”. • Files are placed in a directory structure representing the namespace structure. 1.6 Constant names All constant names are written in UPPERCASE. This includes TRUE, FALSE and NULL. Words can be separated by underscores - you can also use the underscore to group constants thematically: • STUFF_LEVEL • COOLNESS_FACTOR • PATTERN_MATCH_EMAILADDRESS • PATTERN_MATCH_VALIDHTMLTAGS 1.7 Control Structures The structure keywords such as if, for, foreach, while, switch should be followed by a space as should parame- ter/argument lists and values. Braces should be placed on a same line and break should have the same tab as its case. Usage: if ($arg === true){ //do something here }elseif ($arg === null){ //do something else here }else{ //catch all do something here } foreach ($array as $key => $value){ //loop here } for ($i = 0; $i < $max; $i++){ //loop here } 1.5. Filenames 5 Web Development Standards Documentation, Release latest 6 Chapter 1. PHP Coding Guidelines CHAPTER 2 Laravel Guidelines 2.1 Getting Started All Laravel projects needs to be saved on a Git Repo. Current repository used is Gitlab. To get started with a new Laravel project you need to: • Clone the repo of an existing project or if the project is new use the latest current stable version. • Run composer install. Do not run composer update for projects that are already in the middle of devlopment as it might conflict the composer lock file • Migrate database by calling php artisan migrate • Setup the .env file 2.2 Controllers • Same as in the PHP Guidlines, all method names are written in lowerCamelCase. In order to avoid problems with different filesystems, only the characters a-z, A-Z and 0-9 are allowed for method names – don’t use special characters. • Only controllers related to the Frontend ( public pages ) must be on document root of the Controllers directory • All other controllers must be organized under sub-folders for example /Admin , /Api, /Ajax etc. 2.3 Models • Projects must have a Models directory found under /app folder of a project root directory. An /app/Models folder should be created on all projects when there is none. Model filenames should be the name of the table in UpperCamelCase. 7 Web Development Standards Documentation, Release latest 2.4 Table and field naming • Table and field names MUST be lowercase and use Snake Case ( snake_case ). • Table names should use the plural form of the actual real life object it is storing. Like for example, the table name for blog posts should be posts not post. • Primary keys should be named table_name_in_singular_form_id in the table names. For example table Posts should have a primary key post_id. For tables that are considered pivot tables, a primary key of pivot_id or map_id may be acceptable 2.5 Adding tables, index or inserting sample data • All tables must be created using database migration by calling the php artisan make:migration create_table_name --create=table_name command. Do not use PhpMyAdmin, the console or any other database IDE to create tables. • 2.6 Routes WIP 2.7 Blade and Views WIP 2.8 Unit Testing WIP 8 Chapter 2. Laravel Guidelines CHAPTER 3 Javascript Guidelines 9 Web Development Standards Documentation, Release latest 10 Chapter 3. Javascript Guidelines CHAPTER 4 Frontend Guidelines 11 Web Development Standards Documentation, Release latest 12 Chapter 4. Frontend Guidelines CHAPTER 5 API Guidelines 13.