search

joomla / coding-standards

Joomla Coding Standards Definition
https://developer.joomla.org/coding-standards/basic-guidelines.html
GNU General Public License v2.0
128 stars 129 forks source link

@package file sniff needs better detection #193

Closed mbabker closed 6 years ago

mbabker commented 7 years ago

The handling in Joomla_Sniffs_Commenting_FileCommentSniff which handles detecting if a file needs a @package tag should be improved. For example, running the sniff against https://github.com/joomla/framework.joomla.org/blob/master/phinx.php results in:

FILE: framework.joomla.org/phinx.php
----------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 7 | ERROR | Missing @package tag in file comment
   |       | (Joomla.Commenting.FileComment.MissingPackageTag)
----------------------------------------------------------------------

This is an entirely procedural file and is part of a project which is fully namespaced, so this error should not be raised.

photodude commented 7 years ago

How would we do this? Currently an @package tag is required unless the "file" is namespaced. PHPCS doesn't check the project it checks individual files. (To me this is similar to the issue we run into with the DuplicateClassName Sniff, PHPCS is not package aware at a level of sophistication necessary to make the sniff useful)

I would suggest there are two options here

  1. add a package tag to the file
  2. exclude the file from the Commenting.FileComment.MissingPackageTag for that specific repo with a custom ruleset for that repo. ( as described in the readme )
mbabker commented 7 years ago

Maybe we flip the logic on this. We're reaching a point where more of our project code is now namespaced (or in a project that is only namespaced) than not, so perhaps it's time to make that sniff optional and in projects that still require it, they have to extend the base ruleset to add it.

photodude commented 7 years ago

The great thing about the ruleset.xml is you can create your own and make any of the rules optional as needed by selectively applying rules. as described in the readme examples provided just place the example ruleset in the standards folder of phpcs and it should be installed.

photodude commented 6 years ago

With merging #204 are we good to close this?