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

phpdocs exception for plain test methods

    XMLWordPrintable

    Details

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

      Description

      It has become sort of a de-facto standard to have no phpdocs on test methods in Moodle phpunit tests.

      I am fine with this because:

      • I think the test name should be the descriptive part - as it also is the most commonly shared part of the failure
      • I've seen when people add extensive phpdoc blocks that they easily get outdated as someone adds another few assertions to address whats going on
      • I like this style of commenting for tests:

        function test_foobar_baz_is_a_bad_example() {
           // Explain exactly what test data i'm setting up.
           $foo = new foo();
           // Execute the code.
           $baz = $foo->bar();
           // Now explain each assertion on that test data inline.
           $this->assertTrue($baz);
        }
        

      With this in mind, I propose we make an exception for phpdoc blocks on test methods.

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                1 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: