http://docs.vanillaforums.com/developer/contributing/coding-standard/

Some of that description should be in a README here. Both need a link to each other.

We need to fix our custom comment sniffs.

The standard

Descriptions MUST BE a full sentence with a capital to start and period to end

Short, return and parameter descriptions MUST be included if present

There MUST be one space before and after parameters

What we are currently validating

• The first line of the description can only be 1 line.
• A long description MAY come after
• Param annotations are REQUIRED for every parameter
• A return annotation is REQUIRED no matter what.
• There must be empty comment lines between [short description, long description, params, return].
• You are not allowed to use the @see tag in a class comment. What is the purpose of this?

Acceptance Criteria

Sniff enforces ONLY the following on comments
There is a DocBlock on

• A class
• A method
• A property

I'm not sure if we actually have any but with it being deprecated and all, we should probably get a sniff in here so we can remove any before its removed from the language.

https://wiki.php.net/rfc/case_insensitive_constant_deprecation

When running code sniffer version 3.x with the current standards, you get a `Fatal error: Interface 'PHP_CodeSniffer_Sniff' not found in...

We should have CodeSniffer run on our changes in CI, so that PR's can be focused more on the code itself and the quality of the comments than on minor issues with the code.

The code for our tslint standard (typescript standard) should be moved from its current repo into this one.

Consider the following code:

public function getGlobalKey(): string {

The (): string type hint should be acceptable, but gives an error asking for a space before the colon.

It's possible that this can be fixed by bringing in an already coded standard library and subclassing it.

Notice: Undefined index: in /git/standards/code-sniffer/Vanilla/Sniffs/Commenting/FunctionCommentSniff.php on line 196

Call Stack:
    0.0002     366816   1. {main}() /usr/local/Cellar/php71/7.1.3_15/bin/phpcs:0
    0.0103    1385960   2. PHP_CodeSniffer_CLI->runphpcs() /usr/local/Cellar/php71/7.1.3_15/bin/phpcs:25
    0.0107    1430864   3. PHP_CodeSniffer_CLI->process() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer/CLI.php:113
    0.0512    3333272   4. PHP_CodeSniffer->processFiles() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer/CLI.php:998
    2.6243    6548864   5. PHP_CodeSniffer->processFile() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer.php:653
    2.6244    6549008   6. PHP_CodeSniffer->_processFile() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer.php:1772
    2.6244    6549616   7. PHP_CodeSniffer_File->start() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer.php:1894
    2.6348    6770880   8. Vanilla_Sniffs_Commenting_FunctionCommentSniff->process() /usr/local/Cellar/php71/7.1.3_15/lib/php/PHP/CodeSniffer/File.php:576

This would be a fine template: https://github.com/php-fig-rectified/fig-rectified-standards/blob/master/PSR-2-R-coding-style-guide-additions.md#further-considerations

Our standard should be published to packagist so it can be more easily installed. This would also enable us to use it as a project dependency.

Acceptance Criteria

• We enforce 120 characters.

I'm finding that I'm getting the following error too much: "There must be a single blank line after the last param tag". There are a couple of cases when this is happening that I see:

1. I have an @return tag.
2. I have an @dataProvider tag.

The culprit seems to be in the FunctionCommentSniff. I think we can just get rid of this big if statement altogether.

Trailing commas in arrays

There should be a built in sniff for this.

Spaces around the concat operator

There should be a built in sniff for this.

Spaces before and after various built in logic methods

• for
• if
• foreach
• etc

Acceptance Criteria

• Sniff enforces ONLY the following on comments
• There is a DocBlock on
  • A class
  • A method
  • A property

See "Removal of the Comment Parser" here: https://www.squizlabs.com/php-codesniffer/2.0.0a1-released

[linc@derby community:master]# phpcs applications/addons/
PHP Fatal error:  Uncaught exception 'PHP_CodeSniffer_Exception' with message 'Class PHP_CodeSniffer_CommentParser_ClassCommentParser not found' in /git/addons/standards/Vanilla/Sniffs/Commenting/ClassCommentSniff.php:17
Stack trace:
#0 /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer.php(1324): include_once()
#1 /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer.php(560): PHP_CodeSniffer->registerSniffs(Array, Array)
#2 /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer/CLI.php(822): PHP_CodeSniffer->initStandard(Array, Array)
#3 /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer/CLI.php(95): PHP_CodeSniffer_CLI->process()
#4 /usr/local/Cellar/php-code-sniffer/2.4.0/scripts/phpcs(25): PHP_CodeSniffer_CLI->runphpcs()
#5 {main}
  thrown in /git/addons/standards/Vanilla/Sniffs/Commenting/ClassCommentSniff.php on line 17

Fatal error: Uncaught exception 'PHP_CodeSniffer_Exception' with message 'Class PHP_CodeSniffer_CommentParser_ClassCommentParser not found' in /git/addons/standards/Vanilla/Sniffs/Commenting/ClassCommentSniff.php on line 17

PHP_CodeSniffer_Exception: Class PHP_CodeSniffer_CommentParser_ClassCommentParser not found in /git/addons/standards/Vanilla/Sniffs/Commenting/ClassCommentSniff.php on line 17

Call Stack:
    0.0004     241272   1. {main}() /usr/local/Cellar/php-code-sniffer/2.4.0/scripts/phpcs:0
    0.0084    1770768   2. PHP_CodeSniffer_CLI->runphpcs() /usr/local/Cellar/php-code-sniffer/2.4.0/scripts/phpcs:25
    0.0088    1836344   3. PHP_CodeSniffer_CLI->process() /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer/CLI.php:95
    0.0092    1854912   4. PHP_CodeSniffer->initStandard() /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer/CLI.php:822
    0.0184    1913712   5. PHP_CodeSniffer->registerSniffs() /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer.php:560
    0.0193    2073320   6. include_once('/git/addons/standards/Vanilla/Sniffs/Commenting/ClassCommentSniff.php') /usr/local/Cellar/php-code-sniffer/2.4.0/CodeSniffer.php:1324

Moved from vanilla/addons#282

Vanilla tends not to do variable alignment. It leads to noisier diffs, and is a bit of a PITA. Most our code base doesn't do this. I don't really have any skin in this, but @linc seems to the think we should not enforce this.

Rules starts here.