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

Coding style: Allow no phpdoc for methods that override base class

    Details

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

      Description

      For methods that override base class, e.g. moodle_filter::filter method, it is unclear what to do regarding phpdoc.

      Because the function documentation block is basically supposed to describe the 'contract' of the function (parameters, returns) and not necessarily the detail of what goes on inside it (that would be done with inline comments), and because that contract is defined by the base class method, in most cases the overriding method does not need different documentation from the base class method.

      In Java best practice for this (imo) is to simply not document the method (except for preferably using the @Override annotation). The IDE will automatically inherit correct documentation from the base class.

      PHP does not have the @Override annotation so there are a number of options:

      1. Copy/paste the documentation from the base class, so that it duplicates the 'real' documentation and gradually becomes out of date or poorer quality as time passes

      OPINION: This is very very bad, and it is also what the current coding guidelines suggest if followed literally.

      2. Include a doc block like this:

      /**
       * @see moodle_text_filter::filter()
       */

      OPINION: This is not too bad (no duplication) but it is ugly.

      3. Omit doc block entirely for functions which are defined in base class.

      OPINION: This is the best way to proceed.

        Gliffy Diagrams

          Attachments

            Activity

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                9 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: