I've been convinced for quite some time that comments that describe what the code is doing (instead of why it does it) are an anti pattern and a code smell. But I had never thought about the DRY side of things, and especially the fact that it leads to comment becoming wrong and misleading when one updates the code but forget about comments (and thinking about it I've seen it numerous times in our codebase). That's a very good argument against purely descriptive comments.
Also :
It would be even better if this check would be part of a class so that it could be called like $document->isNew(),but that's beyond the scope of this article.
I don't think it is. Introducing new methods when things get complicated is actually my favorite way of making the code self explanatory and avoid the need for comments
Totally agree, that would be better and avoid a comment, and it could have been included as well. But just extracting the variable makes the same point, and this way I had to to dive less into the class structure 🙂
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I've been convinced for quite some time that comments that describe what the code is doing (instead of why it does it) are an anti pattern and a code smell. But I had never thought about the DRY side of things, and especially the fact that it leads to comment becoming wrong and misleading when one updates the code but forget about comments (and thinking about it I've seen it numerous times in our codebase). That's a very good argument against purely descriptive comments.
Also :
I don't think it is. Introducing new methods when things get complicated is actually my favorite way of making the code self explanatory and avoid the need for comments
Totally agree, that would be better and avoid a comment, and it could have been included as well. But just extracting the variable makes the same point, and this way I had to to dive less into the class structure 🙂