#Do you think comment blocks are bad?

25 messages · Page 1 of 1 (latest)

lost delta
#

Morning.

This is probably more a discussion topic than a help topic, but I think it is okay to post here (I guess?). I've seen many people saying that comments are usually bad, that is, most part of comments aren't supposed to be there. But what do you think? I really want to know the best practices and having a readable good code.

I guess, if your code is quite understandable you don't have the need to add comments, but perhaps a comment block above the function would help some other developer to quickly identify what that function does. On the other side, your function should be already named well in a understandable way.

What is your opinion on this? How do you write comments and do you avoid commenting your code?

PS: this probably sounds way too silly and basic for most of you, but I'm starting now so I could use your points of view.

marsh jay
#

Comment blocks are good.
Of course, if you only set the @param|@return that's not really useful.
Also the description is most of the time useless because of the function name.
But you can put tons of annotations like code samples, more granular type-hinting for array, and more more...

#

Also I like to comment block everything for the sake of consistency, but I could find many functions in my code that don't need doc blocks.

lost delta
#

I mean, there are a few functions (index, for example) that don't need to be commented.

#

But you comment them as well?

#

@marsh jay

marsh jay
#

hell no

lost delta
#

do you follow any standard for commenting?

#

I mean

#

there is a common used "design" for comment blocks, right

marsh jay
#

Example of something that doesn't need to e commented : ```php
/**
* Réinitialise les valeurs du QueryBuilder
*
* @return void
*/
private function reset(): void
{
$this->type = '';
$this->request = '';
$this->body = [];
$this->filtersGroups = [];
$this->sortOrder = [];
$this->fields = '';
$this->pageSize = 0;
$this->currentPage = 0;
$this->expectObject = false;
}

marsh jay
#

I mean the convention is not that complicated.

  • Description
  • Params / any other annotations
  • Return annotation
#

Are you talking about that because of the native type-hinting coming with Laravel 10 ?

#

(You can't type-hint precisely as in Doc Blocks with PHP native type-hinting, sometime you need them.)

lost delta
#

I didn't see laravel new features upcoming

#

I actually asked this question because in my code there was many simple functions, such as store in UserController, for example, that had like 2 lines written in the function itself and 5 lines written in the comment block which looked quite unnecessary to me

marsh jay
lost delta
#

ngl, having comments on the top of each function makes it easier to identify the function (I'm not talking about understanding it, but it is much easier for the eyes to separate functions when there is something separating them on the top)

marsh jay
cinder viper
#

This and describing magic attributes/funtions is about 99% of what I use docs blocks for.

sudden geyser
#

@lost delta I wouldn’t say code comments or docblocks are inherently bad. But as you say, code should be self-documenting. If your code needs a comment to explain what it’s doing that it’s probably too complicated and needs refactoring.

Docblocks, I’m torn on. I’ve used them for years, but PHP is constantly getting better typing that is gradually making full-on docblocks redundant. However, as someone else mentioned, I like them as visually indicators of where a function/method begins. I can quickly scroll through a file and see each function visually separated. But as for the information it conveys (parameters, return type) they’re becoming more and more redundant, but omitting the redundant params/return type plays havoc with my OCD 😅