[policy] Remove the requirement for doxygen for test methods

Created on 10 October 2013, over 11 years ago
Updated 17 October 2024, 7 months ago

Problem/Motivation

It's an absolute waste of time and effort.

Proposed resolution

Update coding standards to say:

Every method MUST be documented, EXCEPT test case methods (e.g., MyTestClass::testFooBar()) when the method name itself sufficiently documents the method's purpose. If more information is needed to describe the the test case, a docblock should still be added. All other methods in test classes (helper methods, assertions, fixtures, etc.) still require documentation.

(proposal from #24)

Remaining tasks

User interface changes

📌 Task
Status

Needs work

Component

Documentation

Created by

🇨🇦Canada chx

Live updates comments and jobs are added and updated live.
  • DrupalWTF

    Worse Than Failure. Approximates the unpleasant remark made by Drupal developers when they first encounter a particular (mis)feature.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • 🇬🇧United Kingdom catch

    @param and @return for new code or any test being updated are now covered by type hinting.

    This does not cover (sorry) @covers but I think we could allow only @covers in that case.

    Helper methods - if they're on an individual test, no docs for me. If they're on a base test class or trait, they should have docs anyway.

  • 🇳🇿New Zealand quietone

    added new issue summary template

  • 🇬🇧United Kingdom catch

    Added myself as a supporter and adjusted the proposed wording change in the issue summary.

  • 🇳🇿New Zealand quietone

    Move the current and proposed text to expected place in the issue summary.

    I suggest the following.

    All classes and all of their methods (including private methods but excluding constructors) must be documented. 
    
    This does not apply to test methods on concrete test classes. Such methods should have a self-documenting method name. When the name is not sufficient documentation should be added.

    What sniffs would no longer be applied to tests?

Production build 0.71.5 2024