
The Code Documentation Fallacy - beagle3
http://voices.canonical.com/jussi.pakkanen/2012/09/25/the-code-documentation-fallacy/
======
exch
I think the article hits on the wrong conclusion. Don't write less
documentation because you're going to assume it will all suck anyway. Insist
on writing better documentation instead.

Having said that, I find it helpful to write documentation before writing the
actual code. Specifically for more complex code pieces for which the behaviour
is not immediately obvious.

For me, writing documentation serves as a form of 'rubber duck debugging'[1]
before the actual bugs occur. Explicitly writing out the intention of a piece
of code in plain English often makes the concept much clearer in my brain and
immediately brings out possible problems with my initial design. Problems I
can fix before wasting time iterating through code implementations.

This is also the reason I very much enjoy writing thorough READMEs for each
library I produce. These explain in abstract concepts what the entire library
API is intended to accomplish. Additionally, I try to include actual usage
examples. As with code-level documentation, this brings up possible problems
before they occur.

The fact that it makes it clear what the code does, months after I last worked
on it, is entirely bonus.

[1]:
[http://en.wikipedia.org/wiki/Rubber_duck_debugging](http://en.wikipedia.org/wiki/Rubber_duck_debugging)

~~~
NickPollard
The best kind of documentation is that which is checked by the compiler and
guaranteed to be correct - the code itself. Code that is well written, in good
style using sensible variable names, can be as descriptive as good comments.
Using a good static type system allows you to encode properties into your code
that are guaranteed to be valid.

I certainly think some comments have their uses - but these are generally at
the level of how systems and modules work, and the concepts used therein, as
discussed elsewhere in these comments. I agree with the article that only 5%
(or less) of functions need individual comments attached.

~~~
kbutler
I've been maintaining some code written with this philosophy, and I find it
lacking.

Code is very good at answering "How" but often the reader needs to know "Why"
or "Why not".

In fact, the maintainer of your code will rarely be reading it to figure out
how it is working - almost always the next person looking at your code will
want to know why it is not working, or will be attempting to change the
behavior.

Comments can guide as to pitfalls that you've avoided in your implementation
and can answer the all-too-frequent question, "What were they thinking?!"

~~~
nimblegorilla
Another problem: It seems like developers in the "clean code needs no
comments" crowd are also the ones least likely to write clean code in the
first place.

~~~
einhverfr
Clean code needs no internal comments, but that's very different from whether
software contracts (which are inherently outside the code operation and
therefore need comments) need comments.

I strongly dislike extraneous comments. But even some clear code needs some
external communication alongside it.

------
thejteam
My problem with code documentation is that documentation is done at the
function or class level. When I'm looking at new code I would prefer a
"concept of operations" describing how the whole thing works together rather
than piecemeal function documentation.

This is especially important with open source code. I'm not going to donate my
time to working with an existing codebase if it is going to take hours to
figure out how it all pieces together. Examples are fine but what I really
need to know is the why. At least when I put up with this at work I'm getting
paid by the hour.

~~~
jostylr
The old classic literate programming paradigm helps with this. It allows one
to write documentation that gives you an overview, provides you with whatever
ordering and connections you feel appropriate and, with my implementation of
it, even takes care of most of the tool chain.
[https://npmjs.org/package/literate-
programming](https://npmjs.org/package/literate-programming)

~~~
andyzweb
this brings a smile to Knuth's face

------
azov
_> When some coder changes the function, it is very easy to forget to update
the comments_

It isn't.

All public APIs should have documentation, even if you believe it's obvious
what they do. This documentation never goes out of date because once you
release your API it tells you what you cannot change. If you changed the code
so that your documentation is now wrong - this code change is a bug and you
should fix it. Because _there 's other code in the wild that relies on the
behavior that you promised_.

Of course in practice you do have to change that behavior every once in a
while. But this should be a big deal (that usually includes bumping up version
numbers, mentioning it in release notes, etc). If you're changing it so often
that updating the damn comment is an issue you either document implementation
details that don't belong in API documentation or your API is unstable crap
and nobody should be using it.

PS. Complaining that API documentation gets out of sync with the code is like
complaining that unit tests break when you change the code. Duh - that's what
they are there for!

~~~
jdmt
I don't disagree that public APIs should be well documented. However, I
believe it's very easy to forget to update the comments. Especially in
scripting languages without type safety. There is little to remind the
programmer that arguments were added, types were changed, argument order was
modified, behavior was changed, return value was changed, locking behavior was
changed, memory allocations were changed, etc. Obviously unit tests should
help catch many of these changes. However, it's still up to the coder to
remember to change the comments. When you're behind on a deadline or you're
juggling 50 different API changes because you're still alpha I'd say it's
pretty easy to forget to update a comment.

See [http://api.jquery.com/jQuery.ajax/](http://api.jquery.com/jQuery.ajax/)
if you want an example of on API that could easily have a few typos in it. Who
is checking to make sure it's 100% in sync with the code 100% of the time? Not
trying to say this example has bugs in the docs but there's a LOT of behavior
described that could be out of date.

~~~
MaulingMonkey
If you're forgetting to update the comments frequently enough to be a problem,
you're probably forgetting to update the code that consumes the API too. That
quality in general falls by the wayside when you're crunching is no reason to
abandon quality altogether.

~~~
dllthomas
Forgetting to change the code that consumes the API means that things don't
work, which is visible right away. Forgetting to change the comments will be
visible gradually and cruft accumulates. Also, sometimes comments wind up
being non-local and just aren't noticed. I agree that in some senses it's "no
excuse" but that doesn't mean it won't happen. Documentation that can break
visibly when things change is better than static documentation.

~~~
MaulingMonkey
> Forgetting to change the code that consumes the API means that things don't
> work, which is visible right away.

Oh how do I wish this were the case!

> Documentation that can break visibly when things change is better than
> static documentation.

Agreed, but I would not call your average run-of-the-mill unit tests
"documentation", nor can all documentation can be programatically tested.

~~~
dllthomas
> > Forgetting to change the code that consumes the API means that things
> don't work, which is visible right away.

> Oh how do I wish this were the case!

It's certainly not always the case, but it's a whole lot more likely to be the
case than for unchecked documentation.

> > Documentation that can break visibly when things change is better than
> static documentation.

> Agreed, but I would not call your average run-of-the-mill unit tests
> "documentation",

I think "is it documentation" is probably more of a spectrum than any
particular threshold, and run-of-the-mill unit tests probably do fall on this
spectrum though I'd probably agree that they're not particularly far along it
(though that surely varies with the habits of those writing the tests).

> nor can all documentation can be programatically tested.

As a practical matter, that's certainly currently the case - tooling is not
set up for testing documentation, and there are things we'd want to check that
would be hard to check in any event. Theoretically also, there are certainly
properties that can't be statically demonstrated. I'm not entirely convinced
that there's nothing _we 're interested in_ that couldn't eventually be got at
_for the programs we care about_ , though it's certainly a possibility.
Regardless, it seems an ideal worth pushing towards, and if tested
documentation is interwoven with untestable documentation such that some
conceptual locality is preserved it's less likely (though absolutely still
possible, to be sure) that you'll forget to update the other when you're
forced to update the one.

------
einhverfr
First, I think more documentation always beats less documentation, assuming
reasonable quality. What the article is getting at is the idea that
documentation for the sake of documentation never results in any quality.

When I write a new module for LedgerSMB (I won't vouch for older code either
by myself or others) I actually start writing the documentation. The reason
here is that the documentation is written primarily to establish the contracts
under which the code operates. This includes concept of operation
documentation as well. It isn't just aimed at other programmers. It is aimed
at documenting the code contracts so that it is clear what are acceptable
operations at first.

So if there is a fallacy it is not that more code documentation is better
(since that is often true, IMO), but rather that telling people to document
for the sake of building documentation works.

~~~
jheriko
"What the article is getting at is the idea that documentation for the sake of
documentation never results in any quality."

X for its own sake is rarely good.

------
oaktowner
One thing to bear in mind is that documentation serves two different
audiences.

One audience is the people who will _use_ your code. For them, every external
method should be properly documented (sure, use a tool for this). And make
sure it's good enough that (barring debugging situations, because you wrote
perfect code) your "users" never have to look inside your code. (If I think
about this in C++, I think you should be able to look at a properly commented
header and never read the code)

And then there's the poor slob who's going to come in and debug/fix your code
some day. He may not need to have every method doc'd but he damn sure needs to
know what's tricky, what's interesting, where the gotchas are, etc.

------
acjohnson55
I've done plenty of dynamic language work where some documentation would go a
long way. In Javascript, every library function should explain what all
optional (i.e. undeclared or reinterpreted) parameters do, what gets returned,
and likewise for all callbacks, plus `this` points to. It's very stylish for
some insane reason not to do this, and it drives me insane.

~~~
mercurial
Don't get me started on Javascript. It's a problem with dynamic languages in
general - the signature does not document what interface the parameters should
implement (eg, a parameter 'file' may be a file path or a file handle, but
you'll only know that by looking at the implementation), but it's particularly
egregious when nothing tells you at first glance which parameters are
optional.

I've now started to document public functions. As my classes usually have few
public functions, but many private ones, the code to comment ratio remains
acceptable, though maintaining the documentation remains a challenge.

~~~
bookface
Agreed completely about how awful dynamic languages can be in this respect.
I've found what helps a lot is consistent naming of parameters. For example,
numberOfWidgets (an integer) versus widgets (a collection) or file (a file
handle) versus path (a string).

~~~
mercurial
Sure, consistent naming helps a lot (though I'm partial to short-yet-readable
alternative like widgetCounts). Sadly, sometimes ambiguity is unavoidable. And
other times, you're just dealing with bad code.

But consistent naming does not help with the "optionality" of parameters.

------
thomasmeeks
Documentation does not exist for your own benefit. It exists to help other
people on the team, or the programmer that inherits your code, quickly
understand your code. The key word here is quickly. Yes, a programmer can
trace code & figure it out. On a large chunk of code, however, that is
exceedingly inefficient. Whether or not documentation is obvious to the person
that wrote it is a very poor test for the documentation's utility.

I used to hold a similar opinion -- "Document the non-obvious". The problem is
that in a project of sufficient size, almost everything can slide towards non-
obvious. Is price the base price, or unit price * quantity? Is the method name
cancel_subscription_and_notify_customer really effective? Of course, I could
use cancel_subscription, but then I'm not telling programmers about the email
that goes out, or cancel_subscription_and_notify, but who am I notifying? The
marketing department? Generally I find really descriptive method names to get
unwieldy very fast. Further, if you say document the non-obvious, the tendency
is towards zero documentation.

The value statement depends on how fast your team grows or changes, and the
expected lifetime of the project.

If you are working on a project alone, and that will never change (e.g. it
isn't something a business relies on), then you probably do not need
documentation. This is also true if you are bringing on a dev a year, and the
team size will always remain relatively small. Similarly, if the project is
relatively short-lived (like a game), then dropping documentation could be a
good idea. Maybe, I'd at least concede there are merits to doing so.
Documentation isn't free, of course.

On the other hand, if you are working at a company that's trying to rapidly
grow, needs to bring on devs quickly, or has developers moving from one
project to another frequently, then I'd say documentation is very important.
You are going to save your team a huge amount of time by taking a little time
upfront to explain what you are doing, why, and the consequences of each
method. Even simple methods deserve documentation for consistency sake.

If your documentation rots, then you handle it the same way as test rot. Make
sure the team knows that docs are necessary, they need to spend the time on
it, and if that means more time for features, so be it. I can say from
experience that writing documentation after the fact is pretty gnarly.

------
mhaymo
The less that is described by the signature, the more necessary it is to
document a function. In C++/C#/Java, while the parameters and return values
are often fairly obvious, exceptions are completely undocumented by the type
system (unless you use Java checked exceptions, which you shouldn't), and so
should be documented manually (and asserted in unit tests, to ensure the
documentation doesn't become incorrect).

------
tjeerdnet
This is an ever ongoing discussion between two kinds of programmers
(documenting and non-documenting). Just decide for yourself or your team what
works best. I myself like to even document other people's code after I see
what the method does if the method isn't speaking for itself. If I am
developing I want to see in my IDE when adding an existing method, a popup
which tells me quickly about what the method does and the arguments it has and
what it returns. Instead of (everytime) having to jump to the code to see what
it does.

Just one simple (real life) example:

    
    
      public String convertText(String text) {
       return text.toUpperCase();
      }
    

This method is already named wrong in my opinion and should be refactored to
something like convertTextToUpperCase to understand what it does without
having to document. But if your methods get more complex I think a little
comment on top of the method describing what's going on really cannot harm.
Especially if the code is difficult to read for new people.

The point is in the end to keep the documentation in sync with the code and
that takes indeed some effort. I myself always make documentation for a method
in Java-doc style, so only above the method, if it's more complex than a
simple getter/setter-method. I always tend to think in terms of the official
Sun Java API-documentation, which I use(d) so often to know how all the
classes/methods work, that it might also make my own code more
readable/understandable when I or someone else has to work on my code if I
have documented it. Inside the method code I try to comment little to not.

@snowwolf: I agree, but it's just an example to show that a method name should
speak for itself

~~~
snowwolf
Just to comment on your example, that method shouldn't exist as it adds no
value to the codebase - it is purely redundant code. Especially if you were to
rename it to convertTextToUpperCase.

The only situation where the method would make sense is if you wanted to be
able to change the implementation in the future (TitleCase, LowerCase etc.),
in which case a better renaming would be covertTextForDisplayInTitles (i.e.
Use the method name to comment why we need to convert the text). That has the
added benefit of also telling you what the method does in your IDE just from
its signature.

~~~
collyw
I was thinking about this recently, and wondered how other people think of
this. Working in a high level language like Python, you can do quite a lot in
one line, for example in a list comprehension.

Should a "productive" one liner be put in a separate method / function with
meaningful name, or better a comment beside it?

I personally find short methods often decrease code readability, as you
constantly have to jump around, and can't read anything from top to bottom.

~~~
peterwaller
My approach is frequently to "name" a complicated list comprehension by
shoving it into a one or two-liner closure function in the current scope. Then
you don't have to jump miles and the code which uses it becomes readable.

~~~
collyw
So what is the advantage of this approach over having a comment beside it?
Sounds slightly more complex to me.

~~~
peterwaller
Because comments can lie.

Also, it can be harder to express the generator in a useful way in English
than the code itself if the code is well written.

The purpose is to make the code as clearly self describing as possible. I
would only do it if it made the code read more like a human language and
remove too much complexity from one place.

------
tsiki
Probably all of us agree that being forced to comment everything will lead to
some bad/useless comments. But the examples you showed were simply bad
comments. Just because there are bad coders out there who don't care about the
quality of their comments for whatever reason, isn't a reason to avoid
comments. I'd treat anyone who wrote that first sample comment in a similar
way I'd treat a programmer who writes unreadable code; that is, probably take
the time to teach them some good commenting practices.

Many of the reasons that speak against commenting apply to good variable
names, too. Maybe someone will come later and change the way the variable is
used but won't change the name. It doesn't mean we should avoid descriptive
variable names, though.

Also, with comments, as with any form of communication, the audience is the
key. Let's say I'm a senior programmer somewhere and I'm writing comments.
Often the train of thought seems to be "well, using this variable name/adding
this comment clears it up for me". But that's usually not nearly enough for
junior coders who are new to the codebase, and who are often the target
audience. They'll probably still go "wtf" after reading a comment aimed at a
senior programmer with an understanding of the codebase and a programming
experience to match.

In addition, the obvious point to make is also that code is good at answering
how, not why.

This is a bit of a pet peeve of mine, I guess since I've met relatively many
coders who claim that good code should comment itself and ditched commenting
altogether. Their code has usually ranged from above average to downright
awful, and has, on average, been rather unreadable.

------
mathattack
There's a principal/agent problem with documentation too. The writer of it
rarely gets the benefit. Many times they will never see or meet anyone who
does. But they have a lot of other competing priorities from highly visible
requesters.

I am interested in examples of companies that get this right.

~~~
redblacktree
I agree with this assessment. Whenever I have the opportunity to get feedback
from someone who has used my documentation, I make every effort to get it, and
then update the documentation. It's gratifying to know that someone benefited
from it.

------
progx
"As a rough estimate, 95% of functions in any code base should be so simple
and specific that their signature is all you need to use them."

Welcome to reality!

What is simple for one guy is really hard to understand for an another one.

What you expect is that every bigger function must be split into dozends of
smaller functions, only to have a cleaner parameter part. But this make the
code flow unreadable.

~~~
kyberias
> What you expect is that every bigger function must be split into dozends of
> smaller functions, only to have a cleaner parameter part. But this make the
> code flow unreadable.

That's exactly what every good, experienced developer tries to do: Splitting
complex stuff into more simpler functions that are easier to understand.
Obviously the end result is not unreadable, on the contrary!

------
mixologic
I'm surprised nobody has mentioned Master Foo and the Programming Prodigy.
[http://catb.org/esr/writings/unix-
koans/prodigy.html](http://catb.org/esr/writings/unix-koans/prodigy.html)

------
samatman
In many languages, the 90% comments from this article are "doc strings", while
the 10% comments are actually comments. They have different uses, and should
be treated accordingly.

I also don't understand the fear that doc strings will go out of date. At
least with dynamic languages that's part of the point: if the doc string is
wrong, then either the contract has changed and not been updated or the code
is fulfilling the wrong contract. Both are useful things to know.

More often, the doc string is correct, and serves both as a guide to the code
"here is what you are about to read" and as a quick summary. if you're trying
to decide, say, between iterate-dirs and walk-dirs, that summary is perfect,
while reading the code would be an annoying digression.

------
paulgrayson
The "turing test" of comments.... If I can distinguish whether the comment was
written by a human or generated by some auto-documenting software then the
comment may be useful; if I cannot tell whether it was written by a human or
auto-generated then it is useless.

------
dexen
...and for those who like concise quotes:

`If the code and the comments disagree, then both are probably wrong.' \--
Norm Schryer

`Don't get suckered in by the comments -- they can be terribly misleading.
Debug only code.' \-- Dave Storer

------
jarrett
My rules for good docs:

1\. Begin with a usage synopsis in the form of sample code. It should hit the
most important functions and show how they fit together. E.g. for a drawing
library, show how to instantiate an image, draw a circle with arbitrary fill
and stroke colors, and write the image to disk.

2\. For each function or method, open your comment with a straightforward
description of what the function does, even if it's _absolutely, undeniably
obvious._ If you're writing an math library, you should even say what the sqrt
function does. It doesn't hurt, it costs you very little effort, and you might
help someone who's just beginning to learn about the problem domain.

3\. For each parameter, document its possible types if your language doesn't
encode that information in the function signature. Even if you're using
something like Haskell where it does, you might need to comment on the type.
E.g. if sin takes a float, say whether it's in degrees or radians.

4\. Provide sample code for functions that have to be used in tricky ways.
E.g. if the function requires special setup or context.

------
informatimago
Ok, the problem is not the documentation. It's the specifications. This
problem is exacerbed by management methods such as Agile/Scrum, where no
specification document is built from the collection of task descriptions
stored in Jira (and IF you are luck to have anything significant in the task
descriptions, more often, from what I've observed, it's hand waving and shin
pointing than anything precise written down).

And even if some specification document is written, it still remains the
problem because when going thru all the phases of analysis design coding and
debugging (whatever the period of the cycle you use), it is not updated!

Now we should probably distinguish API elements from internal implementation
stuff (but the blog article mentions APIs).

When documenting internal stuff, unless you've developped internal APIs (which
you should do!), the documentation can indeed be descriptive, to help
maintainers orient themselves and avoid pitfals.

When documenting API, what you need mainly, is the specifications of the API.
This will be the "contract" with the client code, and if there's a discrepancy
between the API specification and the implementation, then it means there's a
bug (somewhere, of course one could decide that the specifications where
wrong, and need to update the specifications instead of the code). Most often
it will be a bug in the code.

But the point is that either you have tools to track the specifications
elements down to the line of code, so that when you create or modify a line of
code, you have easy access to the specifications, or you put the specification
in the docstrings (documentation comments) in the code, to get the same easy
access. And note that this is a read/write access: specifications may need to
be updated when the code is maintained.

So I would agree, write less documentation, write more specifications. Close
to the code.

~~~
redblacktree
I tried a google search for "shin pointing" and only got pictures of people
doing literally this.

I got it from context, obviously, but can you explain this turn of phrase to
satisfy my curiosity?

~~~
informatimago
i meant it quite literally. You know, in real life meetings, with body
language, odors, hand waving and all that non verbal communication. If
everybody knows what we're taliking about, then what's the point of writing it
down? Yeah, right. Come back six month later and with half the team turned
over, and see how useful thos old Jira tasks with no writte specifications
will be useful...

~~~
redblacktree
Oh, I see. I've always known "hand waving" to be a Star Wars reference. i.e.
"These are not the droids you're looking for."

------
TheDistantSea
So basically the author is making the argument that comment quality is
correlated with quantity.

As far as I can see, this is backed exclusively with "but the ones that do
probably...".

Let's just say I 'm not convinced yet.

~~~
lyesit
I think the argument being made is that comment quality is more important than
quantity. The author gave an example where the code with less documentation
had more useful descriptions in order to illustrate this point; I don't think
he necessarily meant that one caused the other.

~~~
TheDistantSea
That's something we can all agree on, but then why bring quantity into the
discussion? I prefer lots of useful comments over few useful comments.

~~~
JackFr
To paraphrase The Incredibles, if everyone is special, than no one is.

If 10% of the functions are commented, I will assume that those 10% are more
important or have more error prone or dangerous usages. If every function has
a boilerplate comment, I lose that information.

~~~
Aykroyd
You can catch garbage comments in code reviews just as easily as you can catch
other forms of programming garbage during review. The fact that someone might
make a lot of bad comments is not a good argument against commenting, it's a
good argument against bad commenting.

I also think that if people are in the habit of having to comment it makes
them more likely to document things like expected values of the input, what
the return could be expected to be, and if there are any caveats.

------
pasbesoin
At its best, documentation (or a subset thereof) can and does serve as a
cross-reference -- like a cross-reference in an important calculation. If the
two results don't correspond, you know you have a problem. (Even if you have
to explore _both_ paths to learn what the problem really is and where it
lies.)

Something to consider, the next time you find yourself inclined to complain
about documentation. Is it the documentation, or the fact that it's not
_useful_ documentation?

------
adamconroy
I personally favour only commenting on the unusual. I also think that if you
are doing TDD then the tests should do a good job of documenting the code. I
can't count the number of times someone has asked me to explain some code I
have written where my first response is "okay, let's look at the tests".

All that being said, it really depends on the scenario. My second last project
was a shrink wrap product development that ran a million dollar plus
accompanying piece of hardware. This project quite rightly required us to
write thorough and consistent comments and docs. Expensive product, complex
code, high risk = thorough docs. I am currently working for a small rapidly
growing and changing business, where the software is mostly internal. Low
risk, quick development required, constant change, low complexity = waste of
time and money creating and maintaining good docs

------
Zikes
I don't get it, having a few comments scattered about in the source code is
better than having a separate document that fully and succinctly explains the
application API?

And what's to stop you from putting the comment about race conditions in the
Doxygen-style comment?

~~~
brandonbloom
Single-to-noise ratio.

You can put it in there, but I probably won't read it. I basically assume that
all javadoc/doxygen-style summary/@param/@return-style docs are entirely
noise.

I much prefer the "docstring" style comments, especially though in Clojure, or
Python.

Examples...

Clojure:

    
    
        user=> (doc map)
        -------------------------
        clojure.core/map
        ([f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 & colls])
          Returns a lazy sequence consisting of the result of applying f to the
          set of first items of each coll, followed by applying f to the set
          of second items in each coll, until any one of the colls is
          exhausted.  Any remaining items in other colls are ignored. Function
          f should accept number-of-colls arguments.
    
    

Python:

    
    
        Help on built-in function map in module __builtin__:
    
        map(...)
            map(function, sequence[, sequence, ...]) -> list
    
            Return a list of the results of applying the function to the items of
            the argument sequence(s).  If more than one sequence is given, the
            function is called with an argument list consisting of the corresponding
            item of each sequence, substituting None for missing values when not all
            sequences have the same length.  If the function is None, return a list of
            the items of the sequence (or a list of tuples if more than one sequence).
    
    

And on the far other end of the spectrum, here's some C# / MSDN docs:

    
    
        Syntax
    
          public static IEnumerable<TResult> Select<TSource, TResult>(
              this IEnumerable<TSource> source,
              Func<TSource, TResult> selector
          )
    
        Type Parameters
    
          TSource
            The type of the elements of source.
    
          TResult
            The type of the value returned by selector.
    
        Parameters
    
          source
            Type: System.Collections.Generic.IEnumerable<TSource>
            A sequence of values to invoke a transform function on.
    
          selector
            Type: System.Func<TSource, TResult>
            A transform function to apply to each element.
    
        Return Value
          Type: System.Collections.Generic.IEnumerable<TResult>
          An IEnumerable<T> whose elements are the result of invoking the transform
          function on each element of source.
    
        Usage Note
          In Visual Basic and C#, you can call this method as an instance method on any
          object of type IEnumerable<TSource>. When you use instance method syntax to
          call this method, omit the first parameter. For more information, see
          Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).
    
    

Entertainingly, this is only _one_ of many overloads in the C# version. The
Clojure and Python functions are variadic with parallel traversal of
collections. Those languages spend their precious docs space covering the
corner cases.

~~~
toolslive
What about this?

List.map : ('a -> 'b) -> 'a list -> 'b list

In languages like OCaml, or Haskell the signature provides a lot. In this
particular case, if you think about it, you conclude that it's almost
impossible to build any other implementation: You get a function from 'a to 'b
and a list of 'a thingies. Now how on earth do I use these to get to a list of
'b thingies? No documentation needed IMNSHO ;)

~~~
strager
Apply reverse, tail, etc. on the result of 'map' and you get something of the
same type. Types don't tell all.

~~~
FreeFull
What if you use a vector whole length is indexed by a Natural in the type
signature? It would still allow permutations and such (like reverse), but not
tail.

Using a dependent type system, it would actually be possible to statically
ensure that map can only map, and do nothing else whatsoever, but it does
become rather unwieldy.

------
Jare
I personally think that leaving a function-level comment snippet empty is
better than either filling it with useless information, or not having it at
all. It serves as visual separator, and it's ready for me to fill when I have
something to write.

------
narag
So true! This is what happens when comments are produced because some coverage
goal.

It's sad how comments here are being (on purpose?) misrepresenting the point.
Another methodology jihad?

Edit: LOL! inmediate downvote. I have my answer now.

------
NAFV_P
As an amateur coder I started commenting in my code only recently. There are
two main reasons for this, to enable others to read my code more easily, and
secondly to enable myself to read my code more easily.

printf("If you use C macros"); int _i=1729; while(_i--) printf(" that are
defined in terms of other C macros"); printf(", you will be in a world of hurt
" "unless you have good documentation written by a human.\n");

------
userulluipeste
TL;DR: The people may be stupid, or may do a messy work, therefore it must be
the methods they use or the requirements that are faulty in the first place.

~~~
ZoFreX
Better TL;DR: Would you rather have 10% of functions commented or 90%? Author
argues that 10% is better, if all functions are documented then documentation
is obvious, noise, and often wrong. Document the non-obvious cases.

~~~
userulluipeste
Would you rather go to one extreme or to the other one?

Please downvote me again.

------
dancecodes
My emacs+doxymacs doing it semi-automatic - I dont know how, but hope these
tags @param will show flyhelp at mouse pointer when moving over params.
Eclipse doing that but not emacs currently. Its all that I need. Often forgot
parameters description and orders.

But agree often documentation older than code. Its very fast older and add
many noise.

------
restlessdesign
Here is a box.

You can choose to have it filled 90% of the way or 10% of the way. Most would
choose 90%, right? But guess what—

THE BOX IS FILLED WITH BEES!

~~~
dllthomas
If I'm a beekeeper, that might be what I want...

------
efnx
I think the effectiveness of guessing what the function does by its
parameters' types and its return type depends on whether or not the function
performs side effects. That said, if it doesn't, or can't (even better), then
the name and types should be documentation enough.

------
ddebernardy
OP is a bit extreme in his conclusions, but not entirely incorrect either.

Insofar as I've experienced, there's a mostly finite amount of goodwill that
will go into commenting. Extra comments once that limit is reached tend to be
sloppy or useless.

Essentially the same for unit tests.

------
jheriko
i think this is still a half way house.

code is documentation. bad source code is hard to read, or in practical terms
- slow to read. good source code has minimal comments and documentation.

writing documentation before you actually need it is often a waste of time as
well. at this point surely you have a design to follow, or something other
than a brainless application of 'documentation' to store that valuable
information into?

as many commenters already point out what you almost always want is very high
level documentation, and I think this should be present as a design (assuming
you have one), if you don't have one then you need a wiki or something.
Something that doesn't pollute your code with garbage...

------
djyaz1200
Saw a group pitch a product that was like RapGenius for code documentation,
don't think it went anywhere? Both writers and users could add their
commentary in a layer that was separate from code, seemed like a clever way to
address documentation?

------
digitalmaster
Personally, I would rather a useless comment (which I will ignore if the
endpoint signature is self explanatory) than no comment at all.

