PetaSoft Knowledge Base

Programming. Requirements

1. General principles

1.1. Do not duplicate the code.

1.2. Tabulate the code.


2.1. Leave comments only for description not obvious parts of code. Use names of variables and functions to describe the logic of code.

2.2. DocBlock.

2.2.1. Set DocBlock for public methods.

2.2.2. DocBlock are important for PHP – they explain type of params and result type.

2.2.3. Write "@return void" if method return no result.

2.2.4. Change DocBlock on changing the result type or .

2.2.5. If method's name can't describe what method do add clarifications to DocBlock comment, but don't duplicate name of the method.

2.2.6. Search in the Internet variables types and specifics of declaration for language which you use.

2.2.7. Use DocBlock comment in the beginning of file with markup to provide information about variables available to use.

2.3. Do not leave commented parts of the code.

2.4. If you didn't wrote some part of code write comment with "@TODO" and feature description.

3. Files and naming

3.1. File encoding – UTF-8.

3.2. Name of the file must match the class name.

3.3. Class name

3.3.1. Class name should be the noun.

3.3.2. Class name should begin from capital letter.

3.4. Function/method name

3.4.1. Function/method name should be the verb.

3.4.2. Function/method name should begin from small letter.

3.4.3. If function/method returns boolean, their names should start from "is", "has" or "not".

3.4.4. If function/method made something with data, their names can start from "calculate", "process", "handle" or "parse".

3.4.5. Getter name should starts from "get" and contains property name. If method gets some data from some database, its name should starts from another word (for instance, from "select").

3.4.6. Setter name should start from "set" and contains property name. If method inserts or updates some data in some database, its name should starts from another word (for instance, from "insert", "put", "update", etc).

3.4.7. Function/method name which init something should be or starts from "init".

4. Coding

4.1. Function/method should return result of one type or null. Or be a procedure – return no result (void).

4.2. Maximum length of the function/method body is 35 lines. Recommended – less than 20.

4.3. One file can contains only one class/object/interface/trait.

4.4. Maximum length of the file should be 500 lines. Recommended – less than 200.

4.5. Maximum length of the line should be 120 symbols (includes tabs which have 4 symbols of length).

4.6. Function/method should not have more than 3 arguments.

4.7. Function/method should not have more than 3 tabulation levels.

4.8. There should be not more than 16 classes/files in one namespace/folder.

4.9. You should follow next sequence of constants, properties and method/functions: constants, static variables/properties, variables/properties, static public functions/methods, public functions/methods, private methods in order of calling.

4.10. There should be 2 lines between groups of constants, properties and methods.

4.11. There should be 1 line between methods.

4.12. There should be no unusable private methods in the code.

4.13. Names of constants, variables, functions/methods, classes should be informative – describe the meaning of the value which variable contains, what functions/methods do, for what classes response. Exception – iterators (i, j, etc) or local variables with obvious usage (for instance, caching the length of the array).

4.14. Code should not contains magic numbers. If you use some number in your code, you should insert it into variable with informative name.

4.15. Class should not have more than 20 public methods (excluding getters and setters).

4.16. Write and implement interface in class if you write the class with complex logic.

5. Performance

5.1. General rule – care about performance.

5.2. If some data available to select by 1 lite SQL-query, don't use more than 1 query.

6. Productivity

6.1. Use global search to find the variables, methods or parts of code.

6.2. Research your IDE to increase you productivity. Recommended for active usage next functions of IDE – live templates, code auto refactoring (and setting the code style), global search (or find in path), search and replace, terminal, file watchers, favorites lists, inspection the code (turned on by default) and hot keys for working with the code.

6.3. Know and use hot keys of your IDE and of your operating system.

7. Other

7.1. Do not use conditions instead returning boolean result. For instance:


// _ for private in JS // turn on E_ALL errors in PHP // @TODO: unit tests // // < ?= ?> in php templates // Use docBlock comments in JavaScript and PHP to define the variables types for IDE // Commit each change. Push tested group of commit with some functionality // JS/PHP: check if variable exists before usage