Hey Dockblock? We're done!
You should write Docblocks
That's an advice, no, a recommendation of good practice I had a while ago. And it's true, you see it written everywhere. So why not? I did. Following best practices, because other told me to.
/** * Whether the user is admin. * * @return boolean */ function isAdmin()
Makes me feel stupid. I will spare the getter and setter examples. Honestly, who on earth will read this and think "Ooooooooooooooooooh! That makes sense now!".
But putting big block of useless comment was a good practice, so I kept doing it.
And we came to a point where we have some @inherit doc things, some @var $stuff in the middle of a function's body. We have so much of these that we don't even read them anymore. We know we have to skip these 5 lines before reading what this function actually does.
But feeling stupid when writing Docblocks while everyone else says it's good, how could I be right?
And I came accross Uncle Bob Martin who said: "You don't have to do it. In fact, stop it" (Clean Code).
If he says this, then it means that some people disagree that Docblocks are a good practice (I am not speaking about public API, just internal code. Docblocks are useful SOMETIMES). I don't have to do it!
It is with pleasure that from now on, whenever I will came accross some stupid comments I put on internal code, I will just delete all of this. And I won't have to comment all these files before pushing to a repo. And when I will actually have a comment at the top of a function, it will mean "Read this, there is something important in here".
That just feels good.