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!
Please or to participate in this conversation.