Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-6216

Coding style: clarify class declaration docs

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Component/s: Coding style
    • Labels:
      None

      Description

      Policy: Class declaration docs cleanup

      Since 23th Oct 2020, these changes have been performed:

      Class declarations

      • Classes must be named according to Moodle's naming conventions.
      • Classes must go under their respective "component/classes" dir to get the benefits of autoloading and namespacing . There aren't such luxuries out from there.
      • Each php file will contain only one class (or interface, or trait...). Unless it's part of old APIs where multi-artifact files were allowed.
      • The brace should always be written on the line beside the class name.
      • Every class must have a documentation block that conforms to the PHPDocumentor standard.
      • All code in a class must be indented with 4 spaces.
      • Placing additional code in class files is only permitted to require artifacts not provided via autoloading (old classes or libs out from the "classes" directories and not loaded by Moodle's bootstrap). In those cases, the use of the MOODLE_INTERNAL check will be required.

      An example:

      /**
       * Short description for class.
       *
       * Long description for class (if any)...
       *
       * @package    mod_mymodule
       * @copyright  2008 Kim Bloggs
       * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
       */
      class sample_class {
          // All contents of class
          // must be indented 4 spaces.
      }
      

      Note the classes PHPDoc style is defined with more detail in the Documentation and comments / Classes section in this document.

      https://docs.moodle.org/dev/Coding_style#Class_declarations

      states: "Placing additional code in class files is permitted but discouraged"

      This is a bit ambigious - for example - it might mean that we can include "in-line functions" - even though we don't have any core code that does that.

      We could update it to be more specific about what is currently allowed (eg include/requires)

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              stronk7 Eloy Lafuente (stronk7)
              Reporter:
              danmarsden Dan Marsden
              Participants:
              Component watchers:
              Marina Glancy, Eloy Lafuente (stronk7)
              Votes:
              0 Vote for this issue
              Watchers:
              7 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: