-
Notifications
You must be signed in to change notification settings - Fork 0
Dev CodingGuidelines Nomenclature
Names of files, classes, and methods are important for a good readability of code.
Language of source code is english, this is necessary for all names of classes, methods, variables and so forth as well as for inline documentation.
All files are stored as UTF-8. However all characters of file, class, method, variable and constant names must be Ascii characters.
Each file contains exactly one class. The name of the file consists of the class name and the file ending .php. The path to the file resembles the package of the class. Source code is stored in the src/main/php folder. Example: the class net::stubbles::lang::stubRegistry is stored in the file src/main/php/net/stubbles/lang/stubRegistry.php.
Test cases are stored in the src/test/php folder. Each class has its test case in the same package, but in the test folder. Example: the test case for net::stubbles::lang::stubRegistry is stored in the file src/test/php/net/stubbles/lang/stubRegistryTestCase.php.
Exceptions to the one class per file rule are:
- net::stubbles::stubClassLoader: the file needs to contain more than one class as this is code required by the class loader itself.
- Test cases: test cases may contain little helper classes as well as long as this helper classes are only used in this test case. If a helper class is used in more than one test case it should be moved into its own file.
Files containing no PHP source code should be placed into src/main/resources respective src/test/resources if they are only required for the test cases.
Class names are nouns. They are written in CamelCase notation and are prefixed with stub. Valid class names are stubExample, stubAnotherClass and stubOneMoreExample.
Exceptions to the prefix:
- net::stubbles::util::Binford: this class is powerful enough so it does not need the prefix.
Please note: the prefix requirement will be dropped once Stubbles is ported to make use of the namespace feature of PHP 5.3.
Interfaces follow the same rules as classes. If possible interfaces should end with able, e.g. Cacheable, Iterable. If this does not make sense in the concrete situation the interface should never reference a concrete implementation, these names are reserved for classes implementing this interface:
interface stubRequest
{
...
}
class stubWebRequest implements stubRequest
{
...
}
Functions are discouraged.
Methods are verbs and follow the CamelCase notation. They always start with a lowercase letter.
Methods setting a property of a class are prefixed with set, methods returning property values are prefixed with get. In case the return value is of boolean type the prefix should be is or has.
If the class offers a fluent interface setter methods do not have to be prefixed with set, but need to return the class instance.
Names should be selected in a way that code can be read like a sentence:
$rss = stubRSSFeedItem::create('title', 'http://example.org/', 'description')->byAuthor('mikey')->inCategory('example')->publishedOn('2008-08-05');
Variables follow the CamelCase notation. They always start with a lowercase letter. Variable names should be expressive on the purpose of the variable. Variable names like $a or $foo are discouraged.
Definition of global constants is discouraged. Only interface and class constants are allowed.
Constant names are always uppercase. To increase readability single words are seperated by an underscore. Example:
class Example
{
const STATUS_OK = 1;
}
The following constants are always lowercase: true, false, null.
Next: Comments