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.

Honestly. This?

/**
 * 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.

I quit

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).

At least!

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.

Published almost 3 years ago