Be part of JetBrains PHPverse 2026 on June 9 – a free online event bringing PHP devs worldwide together.

khaliwell's avatar

PHP commenting preferences

I'm really just looking for other peoples opinions on how you comment thing.

Previously (~3 months ago) I would add docblocks (variable/parameter types & return types primarily) on methods/functions as well as properties. I generally didn't (and still don't) add them on classes. I would also add a brief description of what the point of it was.

Recently (within the last 3 months) I started leaving off the brief description because what I found was A) I changed how I was naming things to be more focused & less ambiguous, B) it created a lot of code smells because I would slightly change what something would do and forget to update the comments.

Now I'm not saying I never add a description, but I stopped adding them for basic CRUD methods in a controller, for example.

But now what I'm realizing is the docblocks are literally just duplicates of the functions/methods 99% of the time since I started using PHP 7.1. I type hint pretty much every parameter either with a scalar type or a class/interface. Same thing with return types, I started using the "function someThing(): string {}" syntax. So, it seems weird and like a waste of time to say the same thing twice. But I'm kind of conflicted about it, which is why I am looking for other peoples opinions.

Again, there are exceptions where I can't describe something in PHP syntax (like if a method can return multiple types), so I would still always use a docblock there, even just so PHPStorm can tell me when I'm trying to use a method what it's supposed to return. I also use inline docblocks to type hint variables, again for the benefit of PHPStorm.

So mostly, I just want to know how & what you comment?

Thanks!

0 likes
0 replies

Please or to participate in this conversation.