We've all seen documentation blocks like this:

    /**
     * Get the value of instructions
     *
     * @return  string|null
     */
    public function getInstructions()
    {
        return $this->instructions;
    }

It's that specific kind of useless: it's bigger than the function it describes, which isn't automatically a bad thing, but it contains no more information than the function itself. I suppose it gives us some type information, which I don't hate.

That particular block come from Sandra, still at InitAg. And while that block doesn't really rise to the level of a WTF, the way documentation is used in the codebase does: it's just doc-blocks like these. They basically all recount the signature of the method and fail to add anything more. It took Sandra hours of combing through the code to understand what the "instructions" in question here actually were.

It's a perfect case of "working to the metric". Someone had a requirement that every function needs to be documented. Now every function is documented. That this documentation gives you no clue about the role of any given property or object is irrelevant: the linter will pass because every function has comments. Mostly useless comments, but comments.

But just to confuse things a bit more, I suspect the previous developer got their start in Python, just based on their setter method:

    /**
     * Set the value of instructions
     *
     * @param  string|null  $instructions
     *
     * @return  self
     */
    public function setInstructions($instructions)
    {
        $this->instructions = $instructions;
        return $this;
    }

Return "self", eh? I suppose I should give them bonus points for attempting to make a fluent API for their setters- you could theoretically do something like:

  myObj.setInstructions("some instructions")
    .setRecurrence(someRecurrenceInterval)
    .setOtherProperty(someValue)

Of course, despite including the hook for it, no one has written any code that does that. If only there were some better documentation to make that clear to developers.

[Advertisement] Keep the plebs out of prod. Restrict NuGet feed privileges with ProGet. Learn more.