Should comments in code be considered failures in coding?

What is the definition of "failure" in this context? It means something bad will happen or happened, right? But what? What are the consequences?

Uncle bob is not a practicing programmer, he's a career preacher. Nobody should pay any attention to anything this buffoon is saying.

Literate Programming is the right way to go, and it's exactly the opposite to whatever he's preaching.

As for keeping comments up to date - that's exactly what code reviews are for. And it's far easier to do with comments which are in line, close to all the code changes you're making. What is really insane is to try to keep all your fancy Confluence pages documenting the design decisions in line with the code, and good luck coming back to a 5 years old branch to only find stale links and no relevant information in any external documents whatsoever.

Should code be written in a way that's expressive enough on it's own?

The majority of my code is written as expressive as possible. Especially naming of variables, functions, interfaces and classes can already have a great impact here.

Note that this is also a great responsibility for the architects and lead engineers who design and model the software architecture. If they fail on their level to provide clear and understandable interfaces and APIs, you can't clean this mess up with expressible code.

If you disagree, what are your thoughts on keeping comments up to date with changes?

I would always comment parts of code where event minor changes can have big consequences, not matter whether the code is expressible or not. It's like the "STOP" or "DANGER" sign to cause attention.

And of course any externally consumed API is documented regarding it's functionality, expected input / output and potential exceptions.

Is there a grey area? Examples?

Hard to create definite "rules" on when code should be documented or not. I think a good indicator is when parts of the code are heavily discussed during a code review it should be documented with whatever was the controversy and how it got resolved.

In most cases I could agree with this. However the big hole in this universal statement, is that it has to assume that a given language is capable of clearly expressing any possible situation. They aren't.

Where it goes even more off the rails is when we are talking about performance optimizations. There is a funny comment war where the RavenDB CTO reviews the code of LightningDB. The RavenDB guy is picking on things like reusing a variable for multiple purposes. The LightningDB guy comes on the thread and says he avoided a stack allocation for perf and you can figure it out if you read the comments. And it goes on like that for a while. Code that is human readable often isn't the best performing at the machine level.

Anyway, I would take it more as a solid guideline for healthy code and less as a hill worth dying on.

I feel for the most part comments should not be necessary and are a failure.

That said, I think in the case of describing why you are doing something(in the case of a strange business requirement or marketing has decided to name something that makes things unclear) then a comment is a good fit.

Also sometimes due to an outside library or dependency or new tech, you need to do something hacky. There a comment due to why its hacky, what went wrong, what part of it is the hack, and how to investigate if there's a better solution when a dev comes to it later, is a good choice. In addition maybe make a card to document that tech debt and investigate it in six months or a year can also be a good idea there. Accept that you've 'failed' but also sets you up to maybe succeed later. :D

As a contradictory scenario, consider that a lot of popular languages and frameworks have core functions that are confusingly named or poorly documented or have unexpected behavior for particular sets of arguments. It’s not malicious; everyone generally does their best and choice quality deteriorates over time as expectations rise. But core functions are how we accomplish our goals on those platforms so we don’t have the choice to avoid them. I’m not sure how I would explain a specific use of such a function to future developers or warn them of its inherent and unavoidable precariousness without a code comment.

I’m not so much a fan of looking for general rules about code comments and quality to make judgements of highly contextual choices. I’m much happier accepting ambiguity and examining behavior in terms of the systems and externalities that shape it. On this subject in particular I’ve learned to understand that “this code is a failure” often just means “I personally don’t like it” and nothing more. I’ve read a lot of what Bob Martin has to say and I don’t really get the sense that he agrees.

Business logic, links to API documentation, annotation (code-in-comments, ugh, but required for some frameworks), that sort of thing.

There's nothing wrong with comments, but if they're explaining something that should be obvious, go ahead and refactor it to be obvious.

Referring to commented code as "overcooked" is interesting as that's what is actually happening in many cases.

This is false dichotomy that you can use only self-explanatory code or only comments. You can use both. Self-explanatory code can't answer the question "why" (at least not as easy as a comment can).

Well, I'm just a beginner. I've gone through some interesting github projects with really large code base, lots of files and I can tell that what stands out the most are the good descriptive comments that tell you what the file or function is, what it does, how it's used and so on.

Sure, the less comments the better. Good expressive code is essential for writing clean code. But comments are a faster way to help developers get a better understanding among lots of code.

If you don't write any comments at all, I think you're not considering other developers