Coding Standards

྅༻ Ǭɀħ ༄༆ཉ edited this page Jan 26, 2014 · 7 revisions

Patches are very very welcome, but they have to be very very compliant to YOURLS Coding Standards or they'll otherwise be rejected.

#1 Rules Or Die

  • Readability is more important than cleverness or brevity.
  • Submit a patch against the current development version in the master branch, not the latest official package available. Also check for potential branches in which your feature or bugfix may be already taken care of.
  • If not already done, read our Pull Request guidelines.

Naming conventions

Use lowercase letters and underscores in variable and function names (never camelCase like doTableResult). Use unambiguous and self-documenting names instead of generic and meaningless names (eg function2() or global $a)

In core patches, always prefix all your PHP functions with yourls_.

In plugins, prefix everything (functions, classes, global variables, HTML elements...) with a unique and personal prefix such as joe_myplugin_

Comments

There are never too many comments and we'd rather strip a few out before committing a patch than pull our hair trying to understand what's going on.

For simple explanations, use inline commenting. For larger explanation, don't hesitation to break in multiple lines using /** ... **/

Indentation and White Space

Your code must reflect logical structure and be easy on the eye

  • Use blocks of 4 spaces at the beginning of a line
  • Align as many things as possible where it improves readability
  • Vertically align begining of line blocks and end of blocks with opening and closing parenthesis (), brackets [ and braces {}

Put white space anywhere it will make your code breathe

<?php
// if, elseif, foreach, for and switch blocks
foreach( $array as $key => $value } { ...

// define a function
function do_stuff( $param1= 'foo', $param2 = 'bar' ) { ...

// call a function
do_stuff( '31337', other_func( 42 ) );

// white space around variable array items 
$x = $foo['bar']; // string, no space = OK
$y = $foo[ $bar ]; // variable, need spaces

PHP tags

Never use shorthand PHP tags, because some servers are not configured to interpret them. Always use full PHP tag.

Correct:

<?php ... ?>

Forbidden:

<? ... ?>
<?= $var ?>

It is also best to omit the final closing PHP tag of a PHP file

Turn debugging on

Always develop with error reporting on. In YOURLS, this means you should add this to your dev config.php:

define( 'YOURLS_DEBUG', true );

Don't hardcode a URL or path

Users may have their plugins in any directory, not just /user/plugins. They may have renamed your plugin directory. They may use https instead of http.

Don't hardcode any path or URL, there are functions for this, such as dirname(), yourls_plugin_url() or yourls_admin_url().

Don't hardcode echoed strings

If you need to output text, don't hardcode it in English, but use the Translation API.
Bad: <?php echo "some message"; ?>
Good: <?php yourls_e( "some message" ); ?>

Read YOURLS in your language and, more specifically, i18n for developers for more.

More links