If it's that convoluted, try refactoring it to smaller pieces.

In theory, there is no difference between theory and practice. In practice, there is.

Half of all programmers are below average capability. Most programmers think they are above average capability. Therefore, as you are a better programmer than average, the chances are the maintainer will be below your capability. Commenting code you barely understand will likely not help him with this disability so you have to fix the code.

@mattnz: below median. A lot more than half are below average.

@mattnz: more directly, at the time you write the comment you are steeped in the problem this code solves. Next time you visit, you will have less capability with this problem.

"What" the function or method do should be obvious from its name. How it does it is obvious from its code. Why is it done this way, what implicit assumptions were used, which papers one need to read in order to understand the algorithm, etc. - should be in comments.

@mattnz, why are you assuming a symmetric (e.g., a bell curve) distribution?

I feel many of the responses below are purposefully misinterpreting your question. There's nothing wrong with commenting your code. If you feel you need to write an explanatory comment, then you need to.

@SK-logic I'd say what the function or method does, what are the arguments and how it handles special cases should be described in the comment that precedes the method. The method name needs only be explicit enough to be able to pick the correct one in autocompletion.

The responses to my comment prove one thesis I have. Many programmers are geeks who would rather argue median vs average and bell curves rather than laugh at a joke. My guess is they are the ones that put themselves at the top of the bell curve (that is not a joke).

@TonyEnnis Not really, but I think they could be put in simpler terms. For example, from the question: "comments should explain 'why', but not 'how'" - this is an argument for what Prog is questioning, not against as the question seems to indicate. Explaining a complex algorithm is explaining why you do a bitshift here or a comparison there, rather than something like foo << 2; // bitshift 2.

@FlorianF, only if you're using something like JavaDoc, or Lisp's doc strings. Otherwise such comments are useless and hard to navigate from an IDE.

@mattnz, my point is that the vast majority of the developers are of pretty much the same capability. All that "10x programmer" stupid myths are irrelevant in the real world. Assuming that everyone else knows the same stuff as you do is almost always the safest way.

Depending on your processes. This type of comments might be better put inside the Business Requirement Document or the Technical Specification Document.

Not exactly a perfect answer so I'll live it in the comments bud-dum-tiss, but what you many understand as clear and concise English may be of very little use to someone else. While things like ` //Test to see if file exists and is valid if (File && FileLocation && FileMimeType && FileMimeTypeValid) ` make sense and may reduce reading time for a debugger/maintainer, it's very likely that in complex blocks of code your understanding of what it's doing will not carry over to someone else, because the language you comment in is more ambiguous than the language you write it in.

"A human can understand a piece of English much faster that he/she can understand a piece of code with the same meaning (as long as the operation isn't trivial)" I disagree. I find code much easier to understand than English, and the less trivial the concept, the easier code is to understand than English translation.

asked and thoroughly answered in “Comments are a code smell” and in answers to multiple questions linked to it

TLDR: "What's wrong with comments that explain complex code?" Nothing. It's the complex code that's the problem, not the comments.

I think it is worth noting that you can only truly understand what a function does by looking at and understanding the code. That is where the truth is. A comment can lie. A responsible programmer will read and understand the code anyway, making the comment obsolete.

My main reason for inline comments is not to say anything about the code, most often its to detail requirements or customer decisions, e.g. "//customer wants this list reverse sorted".

I don't like reductive schools like Robert Martin's for this reason. Yes, this is all well and good, except that if you have to satisfy a complex requirement sometimes complex code is required to do it.