I would say that if you read Clean Code then you should also read A Philosophy of Software Design (amazon.com/Philosophy-Software-Des...) to get another view on the matter. Just because Uncle Bob wrote something in Clean Code doesn't make it the only way to see things. There are some problematic things with the Clean Code view that makes code harder to read.
Father and husband; Android Engineer and Quality Advocate; For fun, I enjoy playing video games, guitar, and table top games. I also dabble in hobby game dev and pixel arts.
But within his presentation (the YouTube link) he explains how he personally does it with his IDE just to avoid having comments all over the place.
The main problem with comments is that they will not be updated after changing some lines of codes. Or maybe a function has a comment how this function solves a problem by using XY. But if XY gets changed maybe the comment for XY will be updated but the calling functions will not receive an comment update.
as an example lets think about you have a function that uses another function to sort an array:
the comment says this method uses bubble sort to sort the array
now someone goes to the function that actually sorts the array and updates it to use quick sort algorithm
he changes the sort comments
because the method still does the same - sorting an input array - the underlying code can be changed.
outer functions that uses the sort function have documentation that maybe says: calls an sort function that uses bubble sort.
this leads to wrong documentation if the person who changes one function only change the comments above the changed function and not in EVERY function that uses the function
This is just an very easy, understandable problem that should describe the problem with having comments everywhere. You can easily exchange the sorting algorithms and the call hierarchy with other things, but the comment-problem still exist.
This is dumb advice if taken literally. 99% of code comments may be useless. But the comment that says "this seems like it should be done more easily with this other feature, but bug-NNN forced us to do this" can save a lot of work in the future.
Honestly, these comments that say please refactor are the worst.
Please avoid them in a team. Use your Repository Tool (Bitbucket, GitHub, Gitlab, etc) to add a comment within the tool and add an issue/ticket as soon as possible to fix the bug.
Using comments instead of refactoring/fixing the code is one of the worst things to do.
It will lead to unreadable, not maintainable code. Because if you do it once, you will do it everywhere. And instead of having clean readable code you will have old, wrong, buggy, not-optimized functions within the whole codebase. And then you fix one bug and will create multiple others because you did not read the comments... ALL comments because you never know where a lazy developer has done such a thing...
Please, don't do that.
Never... Really... Never
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 have a good advice for every developer.
If possible turn color of your comments to red so that you see them as an error and then try to delete them as fast as possible.
If you still think comments are useful, read this book amzn.to/3B3yUB8
And if you do not want to read the book, see this presentation by the author: https://www.youtube.com/watch?v=7EmboKQH8lM&t=1s
Also, Uncle Bob explains in the book (and in the presentation) how clean, readable and maintainable code can be produced.
To be honest, everybody should read this book!
I would say that if you read Clean Code then you should also read A Philosophy of Software Design (amazon.com/Philosophy-Software-Des...) to get another view on the matter. Just because Uncle Bob wrote something in Clean Code doesn't make it the only way to see things. There are some problematic things with the Clean Code view that makes code harder to read.
I’ve read Clean code and I’m pretty sure he’ he didn’t say comments are bad. He provided cases in his experience where they were and were not useful.
No he did not say that in his book.
But within his presentation (the YouTube link) he explains how he personally does it with his IDE just to avoid having comments all over the place.
The main problem with comments is that they will not be updated after changing some lines of codes. Or maybe a function has a comment how this function solves a problem by using XY. But if XY gets changed maybe the comment for XY will be updated but the calling functions will not receive an comment update.
as an example lets think about you have a function that uses another function to sort an array:
This is just an very easy, understandable problem that should describe the problem with having comments everywhere. You can easily exchange the sorting algorithms and the call hierarchy with other things, but the comment-problem still exist.
This is dumb advice if taken literally. 99% of code comments may be useless. But the comment that says "this seems like it should be done more easily with this other feature, but bug-NNN forced us to do this" can save a lot of work in the future.
Honestly, these comments that say please refactor are the worst.
Please avoid them in a team. Use your Repository Tool (Bitbucket, GitHub, Gitlab, etc) to add a comment within the tool and add an issue/ticket as soon as possible to fix the bug.
Using comments instead of refactoring/fixing the code is one of the worst things to do.
It will lead to unreadable, not maintainable code. Because if you do it once, you will do it everywhere. And instead of having clean readable code you will have old, wrong, buggy, not-optimized functions within the whole codebase. And then you fix one bug and will create multiple others because you did not read the comments... ALL comments because you never know where a lazy developer has done such a thing...
Please, don't do that.
Never... Really... Never