Inline Documentation

[Rumperuu]

We should consider how we want to handle doc comments going forward, as they are currently very unwieldy and make the codebase difficult to navigate and read. As development continues, the problem will be exacerbated if not nipped in the bud now.

Perhaps the best example of this bloat is class/task.php: the file is 2,831 lines long, 1,305 of which are comments:

$ cat class/task.php | wc -l
2831
$ grep '*' class/task.php | wc -l
1305

The filebegins with an 85-line docblock listing every single change made to it over 73 versions. Almost all of these are minor tweaks, bugfixes, etc.

This pattern holds for most of the codebase:

• footnotes.php: 106 lines, 89 of them comments;
• class/settings.php: 1,617 lines, 1,128 of them comments;
• etc.

There is also a 279-line custom documentation schema defined in customized-documentation-schema.txt that is a) inconsistently applied throughout the codebase and b) prohibitively lengthy.

Don't get me wrong, this is all good information to have somewhere, but in most cases the code is not the place for it. In the case of the @since tags that make up the bulk of the doc-comments, for example, that place is (often) the commit history and the changelog in readme.txt, where the information is currently duplicated (with an exception that I'll get to in a moment).

FYI the WordPress Coding Standards cover PHP documentation here.

I propose the following:

• stop the use of custom PHPDoc tags;
• stop using @since to record all updates:
  • per the Coding Standards, ‘every function, hook, class, and method should have a corresponding @since version associated with it’ (indicating when it was first introduced), and additional @since tags should only be added ‘if significant changes have been made to a function, hook, class, or method’ (emphasis mine, and they provide a list of what would be considered a ‘significant change’).
• use @see and @link more sparingly:
  • we do not need to link to every since post ever made on the WP Support Forum;
  • we list contributors in readme.txt; and
  • we can add Forum links in commit messages and/or linked Issues.
• when modifying existing code in future, reduce any associated docblocks in line with these rules.

This way, we should gradually reduce the commentage over time without any undue effort on our parts, and that reduction will be concentrated on those files that we edit most often.

Thoughts?

[markcheret]

It's a good idea to find the balance between a well-documented codebase that is still slick and code readability. If I'd have to give a quota I'd say a max of 20% of the file should be comments and the rest code. Or find a way to document the functionality behind the code separate from the code that's being run and parsed...

We do have a GitHub Page for Documentation that is auto-generated. I'd say let's use what is necessary to generate information required for someone bugfixing or adding features who doesn't know the code.
If they want to dig deeper, we have a wiki, the commit history or the support forum.