mirror of
https://github.com/php/php-gtk-src.git
synced 2026-03-24 09:12:12 +01:00
111 lines
4.1 KiB
Plaintext
111 lines
4.1 KiB
Plaintext
PHP-GTK Coding Standards
|
|
|
|
For internals work (that is, code written in C), aim to adhere to the
|
|
coding standards distributed with the PHP source:
|
|
http://cvs.php.net/php-src/CODING_STANDARDS.
|
|
|
|
For code written in PHP (for example, demo or test scripts and manual
|
|
examples), it has been agreed to adhere to the PEAR coding standards,
|
|
for the most part. The only differences are in the naming conventions
|
|
- please read the final section below carefully, even if you know PEAR
|
|
CS inside out.
|
|
|
|
The full PEAR Coding Standards document, including plentiful examples,
|
|
is available online at http://pear.php.net/manual/en/standards.php.
|
|
|
|
Overview:
|
|
|
|
File formats:
|
|
ISO-8859-1, text/ASCII, Unix line endings, single line feed after
|
|
content.
|
|
|
|
Indenting and line length:
|
|
No tabs, indent 4 spaces, aim to hard wrap at 78 characters (the PEAR
|
|
CS suggests 75 to 85 is 'safe', but in documentation it may not be).
|
|
|
|
Control structures:
|
|
Single space to follow control keyword, 'else' on a single line, and
|
|
always use curly braces.
|
|
e.g.
|
|
if ((condition1) || (condition2)) {
|
|
action1;
|
|
} elseif ((condition3) && (condition4)) {
|
|
action2;
|
|
} else {
|
|
defaultaction;
|
|
}
|
|
|
|
Function calls:
|
|
Single spacing between all elements except the brackets.
|
|
e.g.
|
|
$var = foo($bar, $baz, $quux);
|
|
|
|
In a block of related assignments this can change.
|
|
e.g.
|
|
$short = foo($bar);
|
|
$long_variable = foo($baz);
|
|
|
|
Function definitions:
|
|
The 'one true brace' convention is used. Arguments with default values
|
|
should go at the end of the argument list. Meaningful values should be
|
|
returned where possible.
|
|
e.g.
|
|
function fooFunction($arg1, $arg2 = false)
|
|
{
|
|
if (!is_array($arg1)) {
|
|
return $this->raiseError();
|
|
}
|
|
|
|
return true;
|
|
}
|
|
|
|
Comments:
|
|
/* .... */ and/or // ... should be used within code.
|
|
Docblock comments should be provided. There is an extensive example of
|
|
docblock commenting at: http://pear.php.net/manual/en/standards.sample.php
|
|
|
|
Including Code:
|
|
require_once is used for an unconditional include
|
|
include_once is used for a conditional include
|
|
Neither uses brackets.
|
|
|
|
PHP code tags:
|
|
<?php
|
|
// ...
|
|
?>
|
|
|
|
Example URLs and email addresses:
|
|
Always use example.org, example.com or example.net.
|
|
|
|
Naming conventions:
|
|
Always use descriptive names, and avoid abbreviations.
|
|
Classes: begin with an uppercase letter. This includes Gtk, Gdk et al, and
|
|
it also includes class names in static method calls (e.g. Gtk::main(),
|
|
MyClass::init()). Structurally we need to divert from PEAR guidelines here,
|
|
as we don't have an equivalent hierarchy to reflect: class 'words' should
|
|
also begin with an uppercase letter, e.g. GtkWindow, TheClassThatDoesStuff.
|
|
Functions and methods: GTK+ or PHP internal methods should be lowercase,
|
|
excepting the class name in static method calls (see above). Functions
|
|
and methods written as part of your PHP code should use the studlyCaps()
|
|
convention.
|
|
Private class members: single underscore prefix.
|
|
Constants: true, false and null are lowercase.
|
|
This is where we leave PEAR guidelines completely. In PHP-GTK, the
|
|
structure is such that we cannot have 'pure' internal GTK+ class constants.
|
|
It was therefore agreed to use the format Gtk::INTERNAL_CONSTANT for GTK+
|
|
constants, enumerated values and flags throughout. PHP's own internal
|
|
constants (e.g. PHP_OS) are not affected.
|
|
For other constants in the global namespace (that is, constants in
|
|
your PHP code), class constants should follow the MyClass::CONSTANT_NAME
|
|
format. Global constants should be uppercase throughout.
|
|
Global variables: We can't emulate PEAR completely here, but we can stay
|
|
with the idea of prefixing global variable names with an underscore and
|
|
an uppercase identifier, e.g. $_MYCLASS_global_varname.
|
|
PHP-GTK itself should always be referred to as 'PHP-GTK', as both the PHP
|
|
part and the GTK part are acronyms. If you need to write about a specific
|
|
version in code commentary, the version number should be separated by a
|
|
single space, i.e. 'PHP-GTK 2', 'PHP 5', 'GTK 2'. In file or class names,
|
|
simply omit the space.
|
|
|
|
# vim: set et ts=4 sts sw=4:
|