Coding standards

Suggestions for contributors.

Download: Zip Download: Tar Find on GitHub

If you would like to contribute to Dlayer, please try to adhere to the coding standards I have detailed below, if you have any questions or believe I have missed something, please content me. I am working towards moving to PSR-1/2, there may be minor differences listed below, if unsure please check with me, it could be an error on this page, or I might have deliberately opted for something different.

There is an excellent chance that my code, specifically some of the older code; will not match these guidelines. With all new code, I am coding to the standards, and anytime I touch a file in a non-insignificant way I am updating the code. However, I am not going through the old code to update it just for the sake of matching the standards.

I will not turn away any code that does not adhere to these coding standards; I very much understand how difficult it can be to change after years of development. I am still adjusting to the coding standards, and as mentioned they don't apply to a significant amount of the Dlayer code.

Please just try to ensure that your coding style is consistent, that is far more important than trying to adhere to any arbitrary rules.

Pull requests

All pull requests need to made from a branch in your fork, please also try to give your branch a name that relates to the change/feature you want me to merge. Most importantly, before creating a pull request, please update your fork, so it is up to date with Dlayer/master.

Files

  • Use UTF-8 character encoding
  • Unix formatted, (LF)
  • A line length of 120 characters, this is not in any way a fixed requirement, please let context dictate, don't make code harder to read by wrapping it to hit a particular line length
  • All code and comments should be in English
  • Spaces for all indenting, I recommend four spaces per tab

PHP

  • Please always use <?php ... ?>, never <? ... ?>, disagrees with PSR-1, shoot me!
  • PHP CONSTANTS should all be in UPPERCASE.
  • PHP keywords should be in lowercase, including, true, false and null
  • Braces on their own line for classes, namespaces and functions
  • Braces in line for if/while etc
  • UpperCamelCase for classes, interfaces etc
  • lowerCamelCase for methods and functions
  • lowercase_with_underscores for multiple word variables

I believe it is easier to show coding standards using a visual example, please check the code snippet below, contact me if you have any questions.

			/**
			 * This is the comment for the example class, it should
			 * be a brief overview of the class
			 *
			 * @author Name <email>
			 * @copyright Copyright here
			 * @license Link to license text
			 */
			class ExampleClass
			{
				private $class_property;

				/**
				 * This is a comment for the example method shown
				 * below, method comments should explain the
                 * purpose and if helpful the context in which
                 * it will be used
				 *
				 * @param1 array Description
				 * @param2 boolean Description
				 * @return void Brief description of returned value if necessary
                 * @throws \Exception (if relevant)
				 */
				private function exampleMethod(array $param_one, $param_two)
				{
					// This is a single line comment
					if ($var1 === $var2) {
						// logic
					}

					/* This is an example of a multi-line comment, it
					should detail what is happening below and why */
					switch ($var) {
						case 1:
							// logic
						    break;

						case 2:
						case 3:
							// logic
						    break;

						// Default case statement always included
						default:
							// logic
						    break:
					}

					for ($i=0; $i<$n; $i++){
						// logic
					}

					$multiple_word_var = 'foo';

					$quotes = 'Single quotes should be used, only
						use double quotes when necessary';

					$array1 = array('value1', 'value2');

					$array2 = array(
						array('value1', 'value2'),
						array('value1', 'value2')
					)

					$sql = "SELECT field_1, field_2, field_3
							FROM table_name
							JOIN table_name_2
								ON condition2 = :value2
							WHERE condition1 = :value1";
					$stmt = $this->_db->prepare($sql);
					$stmt->bindValue(':value1', $value1, PDO::PARAM_INT);
					$stmt->bindValue(':value2', $value2, PDO::PARAM_INT);
					$stmt->execute();

					$model_users = new Model_Users();

					return $model_users->activeUsers(30);

					return $model_users->activeUsers()
                        ->limit(50)
                        ->order('desc');
				}
			}
			
		

JavaScript

The coding standards for JavaScript are as close as possible to the PHP coding standards, below is an excerpt from one of the JavaScript files.


		var previewFormBuilder =
		{
			highlight: false,
			changed: false,
			visible: false,

			/**
			 * Preview function for integer based field attributes, updates the
			 * attribute value in on the form as the user makes changes in the tool
			 *
			 * @param {Integer} Id of the field being edited
			 * @param {String} Field attribute being updated
			 * @param {String} Element attribute that is being updated
			 * @param {String} Initial value for the text string
			 * @param {Boolean} If the value is optional the user should be able to
			 * clear the value, shouldn't default to initial value, if not set
			 * defaults to false
			 * @returns {Void}
			 */
			elementAttributeInteger: function (field_id, attribute, field_attribute,
				value, optional)
			{
				if (typeof optional === 'undefined') {
					optional = false
				}

				$('#params-' + attribute).change(function ()
				{
					previewFormBuilder.highlight = true;

					var selector = '#field_' + field_id;
					var new_value = parseInt(this.value, 10);
					var current_value = parseInt($(selector).attr(field_attribute), 10);

					if (new_value !== NaN && current_value !== NaN &&
						new_value !== current_value && new_value > 0) {
						$(selector).attr(field_attribute, new_value);
						previewFormBuilder.highlightItem(selector);
						dlayer.preview.changed = true;
					} else {
						if (optional == false) {
							$(selector).attr(field_attribute, value);
							$('#params-' + attribute).val(value);
						} else {
							$(selector).attr(field_attribute, '');
							$('#params-' + attribute).val('');
							previewFormBuilder.highlightItem(selector);
							previewFormBuilder.changed = true;
						}
					}

					previewFormBuilder.unsaved();
				});
			},
		}
		

Database

Any contributions which require a change to the structure or content of the database should include two patch files, one to make the required changes and another to undo the changes if anything goes wrong.

If you are only making minor content updates, I will accept one patch file, an undo patch file isn't necessary but very much appreciated if included.

If you review the commits, you will discover very quickly spot I am not following the guidelines for Database changes; I will adhere to them once I have the set-up/reset scripts in place.