Documentation

Every constant MUST be documented.

• Clarity and Purpose: Every constant should have a description explaining its purpose, value, and how it is used. This makes it clear to future developers why the constant is defined and how it fits into the larger context of the codebase.

• Consistency: Documenting constants ensures that the meaning and usage of specific values are consistent throughout the code, reducing the chance of errors or confusion.

Every code line or block MUST be documented.

• Maintainability: Every block of code, especially those that implement complex or non-obvious logic, should have a comment. This helps future developers (or even your future self) understand the reasoning behind the code and any edge cases or assumptions made.

• Collaboration: Code blocks should be documented to make collaboration easier. When working in teams, clear comments prevent misunderstandings and ensure everyone is on the same page.

Every function SHOULD have PHPDoc with at least one sentence.

• Function Purpose: A brief description of what the function does is essential, even if it's just one sentence. It gives context to the function's behavior and helps developers understand its intent at a glance.

• Parameters and Return Values: While not always required, documenting the function's parameters and return values is beneficial. This can improve IDE support for auto-completion and function signatures, which speeds up development.

Every class SHOULD have PHPDoc with version (version should be semantic).

• Class Overview: Classes should have a high-level description of their purpose and the role they play in the system. This is essential for understanding the function of large or complex classes.

• Versioning: Including the version number in the class documentation helps track changes over time. This is particularly important when maintaining a system over long periods, as it shows which version introduced or modified certain features, improvements, or bug fixes.