[kbenson]

> The best kind of documentation is that which is checked by the compiler and guaranteed to be correct - the code itself.

Which lends your documentation to being hard to read for a certain percentage of developers, varying depending on your project.

This strategy, while easy for developers experienced in the target language and familiar with the code, can have real negative consequences if the people involved in the project are of a different fluency level with the language or even CS in general, or new to the project.

Q: What I just coded is obviously quicksort, so why should I label it?

A1: Because not everyone is used to seeing quicksort implemented manually in C, assembly, python, etc.

A2: Because without knowing at a high level what you are trying to accomplish, it's much harder to ascertain whether that bug you just found is really a bug or an interesting feature which will come into play a page later.

A3: Because knowing immediately that this chunk of code does NOT pertain to some specialized code to select items after sorting saves time and cognitive load.

[adamconroy]

You can't go around writing comments for the lowest common denominator. Insanity ensues.

[kbenson]

I don't think I'm advocating that in any way, just at a minimum sanely peppering the code with markers. to keep with the quicksort example, a simple single line comment at the top would suffice:

/* standard quicksort on foo before we make our choice below */

That hardly seems like insanity to me.

[adamconroy]

Maybe not insanity, but I would find it a little noisy reading that code, like having to code at a desk near the receptionist.

I wouldn't mind if the comment said "using qucksort because n is expected to be large". But only if the choice of quicksort over some other algorithm was deemed significant.

[kbenson]

My point is really to just define the block as containing quicksort when the function it's in does other things as well. Refactoring it into it's own function with a useful name would be just as (or probably more) useful. It's really that lack of either which I see as insufficient