Writing comments in your code is fine and dandy but sometimes its just a fucking waste of time. Here’s an example:

<?php
class 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:

<?php
class 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).