Coding Standards

Introduction

This document outlines the coding standards and best practices for the UchuDocs repository. We follow PSR-12, the extended coding style guide for PHP, to ensure consistency, readability, and maintainability across the codebase.

PSR-12 Coding Style

UchuDocs adheres to the PSR-12: Extended Coding Style standard. This standard extends and expands upon PSR-1: Basic Coding Standard.

Key PSR-12 Guidelines

Files

• Files MUST use only UTF-8 without BOM for PHP code
• Files MUST use the Unix LF (linefeed) line ending
• Files SHOULD either declare symbols (classes, functions, constants, etc.) or cause side-effects (e.g. generate output, change .ini settings, etc.) but SHOULD NOT do both
• Namespace and class declarations MUST follow PSR-0 or PSR-4
• Class names MUST be declared in PascalCase
• Class constants MUST be declared in all upper case with underscore separators
• Method names MUST be declared in camelCase

PHP Tags

• PHP code MUST use the long <?php ?> tags or the short-echo <?= ?> tags
• The closing ?> tag MUST be omitted from files containing only PHP

<?php

// PHP code here

// No closing tag

Lines

• Lines SHOULD NOT be longer than 120 characters
• Lines MUST NOT exceed 80 characters; lines longer than 80 characters SHOULD be split into multiple subsequent lines of no more than 80 characters each
• There MUST NOT be trailing whitespace at the end of lines
• Blank lines MAY be added to improve readability and to indicate related blocks of code

Indentation

• Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting
• All PHP files must end with a single blank line

Keywords and Types

• PHP keywords MUST be in lowercase
• PHP types and constants (e.g. null, true, false) MUST be in lowercase

Namespace and Use Declarations

• The namespace declaration line shouldn't contain other code
• All use declarations MUST go after the namespace declaration
• There MUST be one use keyword per declaration
• There MUST be one blank line after the use block

<?php

namespace Vendor\Package;

use Vendor\Package\ClassA as A;
use Vendor\Package\ClassB;
use Vendor\Package\ClassC as C;

// Code here

Classes, Properties, and Methods

• Visibility MUST be declared on all properties and methods
• The abstract and final keywords MUST be placed before the visibility declaration
• The static keyword MUST be placed after the visibility declaration
• Opening braces for classes MUST go on the next line, and closing braces MUST go on the next line after the body
• Opening braces for methods MUST go on the next line, and closing braces MUST go on the next line after the body
• Properties and methods MUST be separated by one blank line

<?php

namespace Vendor\Package;

class ClassName
{
    public $foo = null;

    public function sampleMethod(int $a, int $b = null): array
    {
        // method body
    }
}

Control Structures

• There MUST be one space after the control structure keyword
• Opening braces for control structures MUST go on the same line, and closing braces MUST go on the next line after the body
• The structure body MUST be indented once
• The body of each structure MUST be enclosed by braces

<?php

if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body
}

switch ($expr) {
    case 0:
        echo 'First case';
        break;
    default:
        echo 'Default case';
        break;
}

Closures

• Closures MUST be declared with a space after the function keyword, and a space before and after the use keyword
• The opening brace MUST go on the same line, and the closing brace MUST go on the next line following the body
• Arguments and variables MUST NOT have a space before each comma, and MUST have one space after each comma

<?php

$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

Additional UchuDocs Standards

Documentation

• Use PHPDoc style comments for all classes, methods, properties, and functions
• Document parameters, return types, and exceptions
• Keep documentation up to date with code changes

/**
 * Calculate the total price of items
 *
 * @param array $items Array of items with 'price' attribute
 * @return float The total price
 * @throws InvalidArgumentException If an item doesn't have a price
 */
public function calculateTotal(array $items): float
{
    // Implementation
}

Error Handling

• Use exceptions for error handling
• Log errors appropriately
• Validate input data
• Provide meaningful error messages

Security

• Sanitize all user inputs
• Use prepared statements for database queries
• Implement proper authentication and authorization
• Keep dependencies updated
• Follow OWASP security best practices

Testing

• Write unit tests for all business logic
• Follow the AAA pattern (Arrange, Act, Assert)
• Keep tests independent and idempotent
• Name tests clearly to describe what they're testing

public function testCalculateTotalSumsPricesCorrectly(): void
{
    // Arrange
    $items = [
        ['price' => 10.0],
        ['price' => 20.0]
    ];
    $calculator = new PriceCalculator();

    // Act
    $result = $calculator->calculateTotal($items);

    // Assert
    $this->assertEquals(30.0, $result);
}

Git Workflow

Branches

• main - production-ready code
• develop - integration branch
• feature/* - new features
• bugfix/* - bug fixes
• hotfix/* - urgent production fixes

Commits

• Write clear, concise commit messages
• Use the imperative mood ("Add feature" not "Added feature")
• Reference issue numbers when applicable

Example:

feat: implement user authentication
fix: resolve memory leak in data processing
docs: update API documentation

Pull Requests

• Keep PRs focused on a single change
• Include tests with new features
• Require at least one reviewer approval
• Update documentation as needed

Code Review Guidelines

• Be respectful and constructive
• Focus on the code, not the author
• Review for functional correctness
• Check adherence to PSR-12 coding standards
• Verify documentation is updated
• Look for edge cases and security concerns

Continuous Integration/Deployment

• Run PHP CodeSniffer with PSR-12 ruleset on each PR
• Run PHPUnit tests on each PR
• Enforce branch protection rules
• Use automated deployment pipelines
• Monitor application performance post-deployment

Conclusion

Following these PSR-12 standards and additional guidelines will help maintain a high-quality, consistent codebase for the UchuDocs repository. These guidelines should evolve with the project as new technologies and best practices emerge.