Comments are actually good

It always seems on the web that whenever someone does something bad or poorly, instead of noticing the exaggerated case where it's no good people prefer to take the stance of being anti towards it. Where this has really been bothering me for instance is in the case of code commenting. I've read a bunch of articles lately of people being very anti-code commenting and very pro self-documented code. I'm not really going to reiterate their examples of how code should be self commenting, needless to say that many of the articles go as far as to say:

When you comment your code you have failed.

My biggest problem with this logic, is that code should be self documented but it should also be a black box. I shouldn't have to read your implementation to understand how it works. That is the whole idea of using an API.

From my personal experience of jumping into a game engine with very little code commenting it would be helpful to be able to read a little proper description of a method and expected results rather than stepping through the code or reading it. Also what about the scripters who just use the API to perform tasks? We can't expect them to go through the engine code reading implementation.

Now someone will probably read what I just said and say "Yea of course comments are useful there, and I'm sure those people understood that", but it doesn't matter. When you write on the internet that you've failed if you've needed to comment your code you are perhaps talking to impressionable junior developers who may take that message at face value.

I should be able to understand what your method does without seeing it's guts and glory.

---