Iedereen die met de WordPress Coding Standards weet waarschijnlijk ook dat deze kan controleren op hoe goed de code is gedocumenteerd. Hiervoor wordt gebruik gemaakt van de Squiz.Commenting
sniffs. Bij Pronamic schakelen we deze sniffs vaak uit, omdat het voor maatwerk trajecten vaak niet uit kan om ook de documentatie tip top in orde te hebben. Voor de Pronamic Pay plugin willen we echter toewerken naar beter gedocumenteerde code. Daarom hebben we binnen deze plugin de Squiz.Commenting
sniffs weer ingeschakeld. Dit resulteert momenteel nog in veel PHP_CodeSniffer fouten, zoals bijvoorbeeld:
1 | ERROR | [ ] Missing file doc comment
| | (Squiz.Commenting.FileComment.Missing)
Het is niet altijd even duidelijk wat PHP_CodeSnifer precies verwacht bij dergelijke fouten. De foutmelding geeft wel aan dat er een FileComment
ontbreekt. Hoe deze FileComment
er uit moet komen te zien wordt er echter niet bij vermeld. Na een kleine zoektocht kwam ik gelukkig wat resources tegen met meer informatie hierover: