I've seen what happens to comments in code: Nothing. And that's bad. The first coder writes a comment, yeah, great. Then someone makes a quick change to the code... But guess what, the comment doesn't get adjusted. And suddenly the code and the comment are telling two different stories. Happens all the time.
This is one of the reasons I also prefer the clean code approach: Let the code tell the story and restrict the code documentation to the "why". What a method does should be obvious, but the question will be, why it does that. What is the purpose? Why -12 and not -123? etc. The less redundant documentation inside your code, the better.
Of course, if we are talking about a public API or something, a documentation for the user (which can be in the form of many examples) is great to get started, no doubt about that. Also it's not a bad idea to document that structure of your project, the "big picture" to find your way around.
I've seen what happens to comments in code: Nothing. And that's bad. The first coder writes a comment, yeah, great. Then someone makes a quick change to the code... But guess what, the comment doesn't get adjusted. And suddenly the code and the comment are telling two different stories. Happens all the time.
This is one of the reasons I also prefer the clean code approach: Let the code tell the story and restrict the code documentation to the "why". What a method does should be obvious, but the question will be, why it does that. What is the purpose? Why -12 and not -123? etc. The less redundant documentation inside your code, the better.
Of course, if we are talking about a public API or something, a documentation for the user (which can be in the form of many examples) is great to get started, no doubt about that. Also it's not a bad idea to document that structure of your project, the "big picture" to find your way around.
In your experience, do devs who discontinue the comments really have the discipline to continue the "clean code" paradigma?