wp-plugin-starter-template-for-ai-coding/.wiki/Coding-Standards.md

Coding Standards

This document outlines the coding standards used in this plugin. Following these standards ensures consistency, readability, and maintainability of the codebase.

PHP Coding Standards

This plugin follows the WordPress Coding Standards with some additional guidelines.

File Structure

• Each PHP file should begin with the PHP opening tag <?php (no closing tag)
• Files should use the Unix line endings (LF)
• Files should be encoded in UTF-8 without BOM

Naming Conventions

• Classes: Use PascalCase for class names

  class MyClassName {}
  

• Methods and Functions: Use snake_case for method and function names

  function my_function_name() {}
  public function my_method_name() {}
  

• Variables: Use snake_case for variable names

  $my_variable_name = 'value';
  

• Constants: Use UPPERCASE_WITH_UNDERSCORES for constants

  define('MY_CONSTANT', 'value');
  const MY_CLASS_CONSTANT = 'value';
  

• Namespaces: Use PascalCase for namespace segments

  namespace WPALLSTARS\PluginStarterTemplate;
  

• Hooks: Prefix hooks with the plugin's prefix

  do_action('wpst_hook_name');
  apply_filters('wpst_filter_name', $value);
  

Indentation and Formatting

• Use 4 spaces for indentation (not tabs)
• Opening braces for classes and functions should be on the same line
• Control structures should have one space between the statement and the opening parenthesis
• Each line should be no longer than 100 characters

if ($condition) {
    // Code here
} elseif ($another_condition) {
    // More code
} else {
    // Default code
}

Documentation

• All classes, methods, and functions should be documented using PHPDoc
• Include a description, parameters, return values, and exceptions

/**
 * Short description of the function.
 *
 * Longer description if needed.
 *
 * @param string $param1 Description of the parameter.
 * @param int    $param2 Description of the parameter.
 * @return bool Description of the return value.
 * @throws Exception When something goes wrong.
 */
function my_function($param1, $param2) {
    // Function code
}

Object-Oriented Programming

• Each class should have a single responsibility
• Use visibility declarations for all properties and methods (public, protected, private)
• Use type hints for parameters and return types when possible

class MyClass {
    /**
     * Property description.
     *
     * @var string
     */
    private $property;

    /**
     * Method description.
     *
     * @param string $param Description of the parameter.
     * @return bool Description of the return value.
     */
    public function my_method(string $param): bool {
        // Method code
    }
}

JavaScript Coding Standards

This plugin follows the WordPress JavaScript Coding Standards.

Naming Conventions

• Variables and Functions: Use camelCase for variable and function names

  var myVariableName = 'value';
  function myFunctionName() {}
  

• Constants: Use UPPERCASE_WITH_UNDERSCORES for constants

  var MY_CONSTANT = 'value';
  

Indentation and Formatting

• Use 4 spaces for indentation (not tabs)
• Opening braces should be on the same line as the statement
• Each line should be no longer than 100 characters

if (condition) {
    // Code here
} else if (anotherCondition) {
    // More code
} else {
    // Default code
}

Documentation

• Use JSDoc for documenting functions and objects

/**
 * Short description of the function.
 *
 * @param {string} param1 - Description of the parameter.
 * @param {number} param2 - Description of the parameter.
 * @returns {boolean} Description of the return value.
 */
function myFunction(param1, param2) {
    // Function code
}

CSS Coding Standards

This plugin follows the WordPress CSS Coding Standards.

Naming Conventions

• Use lowercase for selectors
• Use hyphens to separate words in class and ID names
• Prefix classes and IDs with the plugin's prefix

.wpst-container {
    margin: 0;
}

#wpst-header {
    padding: 10px;
}

Indentation and Formatting

• Use 4 spaces for indentation (not tabs)
• Each property should be on its own line
• Include a space after the colon in property declarations
• End each declaration with a semicolon
• Use single quotes for attribute selectors and property values

.wpst-container {
    margin: 0;
    padding: 10px;
    font-family: 'Helvetica', sans-serif;
}

Automated Code Checking

This plugin uses automated tools to enforce coding standards:

1. PHP_CodeSniffer (PHPCS): Checks PHP code against the WordPress Coding Standards

   composer run phpcs
   

2. PHP Code Beautifier and Fixer (PHPCBF): Automatically fixes some coding standard violations

   composer run phpcbf
   

3. ESLint: Checks JavaScript code against the WordPress Coding Standards

   npm run lint:js
   

4. Stylelint: Checks CSS code against the WordPress Coding Standards

   npm run lint:css
   

Conclusion

Following these coding standards ensures that the plugin's code is consistent, readable, and maintainable. All contributors should adhere to these standards when submitting code to the project.