A lot of truth to this, but an exception can and should be made when something merits an explanation of why it is the way it is. Comments should be few and far between in well-written code, but still used when there's an actual need. For me that's usually just when I had to dig to find a way to make something work when a more intuitive solution wouldn't work in that specific case.
Indeed, some business concerns are just impossible to explain by code itself and as you've said, logic that by some black magic doesn't work.
The key is to know if comments are up-to-date with the code as refactors come and go and not everyone updates the comments.
There are comments and comments. The comments explaining what the code does are usually a symptom that the code is convoluted and difficult to understand even for the person who is writing it.
On the other hand, there are comments like:
# This solves a bug in the library Fubar that prevented the Baz
# from being executed. See: https://github.com/fu_bar/baz/issues/454
Or:
# Temporalirly removed as per request in Issue #1243
Currently developing futuristic smart-device, IoT connected, highway construction site safety system in EU.
Used to work on infrastructure, application architecture and cloud engineering.
I've been a professional C, Perl, PHP and Python developer.
I'm an ex-sysadmin from the late 20th century.
These days I do more Javascript and CSS and whatnot, and promote UX and accessibility.
While I agree with not using comments where the code can demonstrate its own purpose and mechanism, I don't like absolutes like "don't use comments". An RFC number or something can be very helpful, or a link to where you found the code you just copy-pasted.
I really like writing code comments, although I don't do it too often. I'm still learning how to make them meaningful first.
I was taught that you should not use comments. To avoid comments your code should be written in a way that can be read like a comment.
I wrote a little article showing the difference of code that needs comments and other that it doesn't.
A lot of truth to this, but an exception can and should be made when something merits an explanation of why it is the way it is. Comments should be few and far between in well-written code, but still used when there's an actual need. For me that's usually just when I had to dig to find a way to make something work when a more intuitive solution wouldn't work in that specific case.
Indeed, some business concerns are just impossible to explain by code itself and as you've said, logic that by some black magic doesn't work.
The key is to know if comments are up-to-date with the code as refactors come and go and not everyone updates the comments.
With this I fully agree, that's something I've been trying to improve on myself.
There are comments and comments. The comments explaining what the code does are usually a symptom that the code is convoluted and difficult to understand even for the person who is writing it.
On the other hand, there are comments like:
Or:
Those make perfect sense to me.
Works very well in commit messages when you have Bitbucket integrated with Jira. Hell of a difference!
While I agree with not using comments where the code can demonstrate its own purpose and mechanism, I don't like absolutes like "don't use comments". An RFC number or something can be very helpful, or a link to where you found the code you just copy-pasted.
So am i.While i agree with Jose Tomas that try to make your code self-interpretation as possible.I'm trying!