Code Style Guide
Welcome to the ThinkUp Code style guide. When submitting pull requests, please make sure that your changes conform to the styles below.
Styles are loosely based upon Drupal’s coding standards, which are themselves loosely based on the PEAR coding standards.
This document is a work in progress. When in doubt, follow the same style as existing ThinkUp code.
Some general style guidelines:
-
Readability trumps brevity: Name your variables and methods something descriptive and readable. The next programmer who is reading your code should be able to understand what’s happening with minimal effort. CPU and memory is cheap; human hours are not.
- Avoid short names that don’t read well. Instead of naming an instantiation of the OwnerInstanceDAO $oid, name it $owner_instance_dao. The extra characters and typing will save future programmers time.
- Avoid overly-generic variable names that don’t indicate what they contain. Never name a variable $var; avoid overly generic names like $data.
- Never say die: Never ever use the die() method. If there’s an error or exception, throw that Exception and let the app catch and handle the exception appropriately up the stack.
- Don’t break encapsulation by globalizing variables: The global keyword is a red flag. Don’t use it. Pass in your parameters or use singletons to access variables.
- Lines should have no trailing whitespace at their end.
- All indentation should not use tabs; use 4 spaces instead.
- Comments, class, and variable names should use US English spelling.
- require_once statements should use single quotes, no parentheses, ie,
require_once 'init.php';
ThinkUp implements the Model-View-Controller design pattern. All new code should follow suit. Read more about ThinkUp’s MVC implementation here.
When organizing and naming new files, keep the following guidelines in mind.
View filenames should match the names of the controllers they correspond with. For example, the public.tpl view goes with the public.php controller.
Separate folder names by a dot. For example, the /account/index.php controller’s view filename is account.index.tpl.
Included template filenames start with an underscore, like _header.tpl
Each file should contain exactly one class or interface.
Prefix filenames with class. for classes, and interface. for interfaces. For example, the CrawlerPlugin interface file is named interface.CrawlerPlugin.php. The User class file is named class.User.php.
Variables: Use lowercase with underscores to name variables, i.e., $view_template, unless it’s a constant. For constants, use underscores with all uppercase, i.e., const KEY_SEPARATOR="|";
Methods: Use CamelCase to name methods, i.e., public function isUserInDB($user_id);