v1.x Code Style

Beans 1.x is based upon PHP 5.2.

We are working to upgrade the codebase to be WordPress Coding Standard (WPCS) compliant. We follow the [WordPress Handbook](https://make.wordpress.org/core/handbook/best-practices/coding-standards/], except for noted below.

• PHP Standards
• JavaScript Standards
• HTML Standards
• CSS Standards

Code Construction

Code Quality

Code quality is a core principle in Beans. We will think about and then implement the SOLID principles of:

• DRY - Don't Repeat Yourself
• Single Responsibility - One reason to exist in the code
• Separation of Concerns - HTML in a view file not in the PHP logic. JavaScript in a script file.
• KISS - Keep it Simple
• and more

If these concepts are new to you, don't worry about it. Stick with these simple ideas.

Make it:

1. Readable - code itself (without comments) is readable and makes sense
2. Reusable - it's flexible enough to be reused in multiple places
3. Maintainable - fixing one thing doesn't break 2 other things

Where Stuff Goes

Use these guidelines to help you figure out where code should go:

• If it's class, then one class per file and nothing else in that file.
• Group like functionality together in a file and folder.
• A function should have one expected behavior when you call it. Keep your functions skinny (less lines of code).

Naming Conventions

Files

Everything in the file

Classes

Functions and Methods

Follow WordPress' naming standards, meaning:

1. lowercase letters
2. underscores render_view() and run()

The exposed functions, i.e. those the child theme and plugins will use, will be prefixed and not namespaced. Naming follows this convention:

beans_verb_description()

Functions do work, such as render, run, check, do, process, etc. Work means they are action-based, i.e. verbs.

The description tells you what the expected behavior is when you call this function. It's clear and expressive. Remember the intent: tells you the expected behavior.

The benefit to that naming convention is: you can read the function's name and know what will happen when you call it.

File DocBlock Header

Of course we want to document our code. Functions and methods should be include a DocBlock in this format:

/**
 * Tell us what the expected behavior is of this function/method when it runs. Start with a verb such as:
 * Checks to see if .... or Filters ..... or Gets the value from xxx when .... etc.
 *
 * Use this area if more explanation is needed.
 *
 * @since versionNumberGoesHere
 *
 * @global $global_variable_name <- if there's a global in the function, list it here.
 *
 * @param dataType $param1_name Tell us what value this parameter represents (will hold).
 * @param dataType $param2_name (Optional) Tell us what value this parameter represents (will hold).
 *
 * @return dataType A quick description of what's being returned.
 * @throws ExceptionName <- if this function has a new ExceptionName, list it here.
 */
function beans_some_function( $param1_name, $param2_name = '' ) {

for example:

/**
 * Convert internal path to a url.
 *
 * This function must only be used with internal paths.
 *
 * @since 1.5.0
 *
 * @param string $path          Path to be converted. Accepts absolute and relative internal paths.
 * @param bool   $force_rebuild (Optional) Forces the rebuild of the root url and path.
 *
 * @return string Url.
 */
function beans_path_to_url( $path, $force_rebuild = false ) {

Function and Method DocBlock

Testing

Everything in Beans will be fully tested. Period.

Why? Tests prove that the functionality is performing as expected and designed. Then when we make a change, the tests run again and confirm that the change did not break anything. If it did, we know where to go looking for the problem.

Yup, tests are important. When submitting PR, make sure you include fully functioning and passing tests with the code.

Not sure how? Ask. We're here to help get you started.