"Don't repeat yourself" is such an important and widely taught
concept in programming, that it has its own acronym (DRY).
Every piece of knowledg...
For further actions, you may consider blocking this person and/or reporting abuse
I have been writing comments for 20 years now and the reason for commenting code is to let my future-self / others understand the reasoning behind it.
A comment shouldn't explain the code itself unless it's very complex (no way around complexity sometimes)
Even a function which returns something very simple sometimes needs a comment, as to why does it even exist?
For example I have a project with many bizzare functions and timeouts which must have a comment to explain they exist solely because of some browser bug.
Many times I also put a link to a stackoverflow/github discussion or to a browser's bug-tracker url.
I also write comments such as instructions to myself to improve some function and how to do it, if it takes too much time to write it perfectly and right now i need to write it dirty just to continue my work.
I LOVE comments and believe a code without comments it like cookbook with just the ingredients and no instructions. yeah ok, this cake needs 3 eggs and a lemon. now please tell me WHY it needs those or I will not comply. I must know the "why" of everything.
The last analogy is not really correct... The code is some kind of instruction. The other suggestions you have mentioned I would consider good comments: E.g. that something is necessary because of a browser bug is not clear by just looking at the code. Also adding a comment if you know how to improve but you don't have time is a good use case (of course it would be better to just fix it right away, but that is very idealistic).
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 🙂
I appreciate the encouragement to think of ways to express meaning more clearly in the code, something I should practice more!
I wonder if a lot of redundant comments are a hang over from the 'pseudo code' approach to writing software, where you start by describing the required logic in a comment, then work through that in real code, which may be more obscure/complex, but leaving the comments to explain yourself...
Yeah, that's something I have liked sooner as well. Write comments first, implement afterwards. It might be a good idea to think about the big picture first, but leaving the comments if the code can easily talk for itself is really a problem.
Explanatory prose is a good comment. Explain the why and how something complex is put together. Future programmers can then more readily understand why something was done, and if that rationale is still applicable.
Comments that just re-iterate what the code is doing are useless comments. Assuming (next point)...
Code that uses good names such that it needn't be commented at all is better than code that uses unhelpful names, and necessitate commenting what the poor code with non-descriptive names is doing.
Comments that do not jibe with what the code is doing are more-than-useless, because the future programmer will be puzzled if the comment is correct and the code is broken, or the code is correct and the comment is outdated and/or specious.
In PHP I find Psalm incredibly useful for stuff like this. It will flag any discrepancies in your DocBlocks and can often fix them automatically. It also supports using DocBlocks to specify some quite complex type information, such as arrays with a specific structure.
Obviously type hints are the best way to specify this sort of thing since they're enforced by the compiler, but they can't always be as specific as DocBlocks can - you can enforce a return type being an array with a type hint, but you can't enforce the structure of said array.
Agree, and if the comment includes information like that, it is not a pure duplication of what the code already says. Different story though if PHP supports generics at some point.
I highly agree. Clean code is a code that is self-explanatory.
IMO comments should only explain business logic - never the algorithmic or syntactic logic.
Great article about comments.
I personally try to write better names at variables and functions with this way the comments should became tiny because the name's would say it all
Your link "compared it to Flow in another article" is broken
Thank you, I am just crossposting here, and the link should go to homepage... That's fixed now 🙂