Writing comments in your code is fine and dandy but sometimes its just a fucking waste of time. Here’s an example:
<?phpclass UserDataAccessClass{ /** * Get the number of followers a user has * * @param string $userID The user id * * @return int */ public function getNumFollowers($userID) { return valueFromAServiceCallOrQueryEtc($userID) }}?>So, yay – that chunk of code passes PHPCS (using the PEAR standard). All the parameters are documented, there’s a line of text explaining what the function does and the docblock even states the return type… how cute!
But why? Why do I have to type all that crap? The function’s name is self documenting & its sole parameter is obvious. The return type makes sense to me but the rest is bullshit. God forbid your function takes multiple parameters; then you’d have to line up the @param’s types and descriptions ’cause PHP people have a strange hardon for lining shit up.
The truth is the only reason I do all that stuff is cuz we run PHPCS on our code at work and I don’t wanna be “that guy”. If it wasn’t a “standrad” at work there’s no way in hell id ever bother.
I’d much have the documentation go like this instead:
<?phpclass UserDataAccessClass{ /** * @return int */ public function getNumFollowers(string $userID) { return valueFromAServiceCallOrQueryEtc($userID) }}?>…And to be 100% honest the only reason I’d include the @return is ’cause I’m an Eclipse & it helps PDT’s static analysis (aka autocomplete gets more better).
