> Code is already a formal specification of what the machine is set to do.

I take back my other comment where I said that "tests are documentation" is the #2 falsehood about documentation that programmers believe. This is the #2 falsehood.

Yes, "formally" the code is the spec. That doesn't help you very much though, squishy human, because you're not a computer.

If English is your fourth language and Java is your second, the English comments aren't necessarily better for the human.

Competent programmers should know all the fine details of the programming language they work in, in effect being human compilers.

if this is a useless comment:

    // set i to 1
    int i=1;

and this is a useful comment:

    // there is a method overload which accepts an array, 
    // but it's buggy and crashes. workaround: cast to tuple first.
    ... 

then you seem to be assuming people only want to write and read the first kind. Because no matter how well you 'know all the fine details of the programming language', comments can tell you things the code can't.

Even aside from the pointless gatekeeping of "competent programmers" - ok what about people who aren't employed as programmers but still need to read and write code? What about the people who just have to deal with it being an unfamiliar language because nobody who knows the language is available?

Is that a useful comment? Seems more like a check style entry.

That comment will apply to every time the overload is available, not for this instance of the call

Substitue any comment that tells you something which the code cannot tell you[1], to see why "competent programmers understand the language thoroughly" is not a good justification for being against comments.

[1] e.g. why the code was written this way instead of another way, or why it exists at all.

That makes no sense. If the array overload doesn't work either fix it or remove it.

A competent English reader would understand what I wrote without any further comments needed, right? Apparently understanding of the language isn't enough. That's the point I was trying to make, but meta.

In this scenario you can't fix or remove it, it's third party library code which is outside your (scope, remit, time or effort constraints).

That's not how software development works.

First you wouldn't write such stuff in comments, that's useless and not what comments are for. Comments are to explain non-obvious things in code, or clarify assumptions that are made, not to narrate that you found bugs but are too lazy to fix them.

If a third-party library is broken, you either fix it or stop using it.

As a developer, you're responsible with ensuring your application works well and is easy to maintain. It doesn't matter if someone else wrote some of the code.

> First you wouldn't write such stuff in comments, that's useless and not what comments are for. Comments are to explain non-obvious things in code,

First, that is a non-obvious thing in code. You look at code someone else wrote, you use your "competent programmer's understanding of the language", you see the overload they "should" have used, you are about to rewrite their function call to cut out the unnecessary cast, and the comment tells you the non-obvious reason why you shouldn't do that. Thus making it a useful comment.

> "If a third-party library is broken, you either fix it or stop using it. As a developer, you're responsible with ensuring your application works well and is easy to maintain. It doesn't matter if someone else wrote some of the code."

If touching any piece of code written by anyone makes it "your application" and immediately mandates that you rewrite all of it to your standards, that is "not how software development works".

You don't rewrite it, you need to maintain it to the same quality standard as your own code'

Onboarding a dependency is something you should weigh very carefully.