The Code Documentation Fallacy
voices.canonical.com
voices.canonical.com
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.
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.
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?!"
I strongly dislike extraneous comments. But even some clear code needs some external communication alongside it.
Some random developer comes at a later time, thinks this code is more complicated than required, refactors it and only then sees why you didn't do it that way. This happened to me many times (both in the "original dev" role and the "random future dev" one).
Comments can easily clarify why this particular piece of work is implemented in this manner and not the others you tried, saving a lot of time to the future devs.
Perhaps most importantly, most of the time you don't need to know how something works, only what it does. Unless you have a reason to doubt that the function does, in fact, do what it says it does, it's much nicer to have a few lines of comments -- written in human language -- to describe the inputs and outputs of some function, or the reason we're invoking some function here, than to have to actually go and read through the code of a function. In fact, reading through the actual code can sometimes impede understanding, because of the reasons I stated above. Now with some functions, this purpose can be entirely expressed in the function signature, but with more complicated functions, that's unlikely.
How about "the bridge is the documentation" for civil engineers? Or "the house is the documentation" who needs building plans?
Documentation also has to cover larger scale interactions, that is how objects interact with each other and how they fit into the design.
All that said, in a large software project you need to pick your battles. Maintaining the same level of documentation across the board and throughout the life of the software is very difficult. Make sure though that your core is well documented and you keep that documentation up to date. Libraries and APIs used externally also need to be well documented.
Note I don't necessarily mean an externally facing API, which I would assume you'd agree needs good documentation. Even if we are on the same team, I don't want to have to read your code just to figure out which of the frob_XXX functions to call. Maybe that is what you meant by your second paragraph?
The code you look at to find the solution might be one 20 or 30 line chunk of Ruby that performs a service for a chunk of 10 year old VB or 20 year old Perl or 30 year old C, or some chain of several languages. A support guy, or apps-level documenter, or maintenance programmer adding a feature, or architect integrating with another system, or business integration consultant helping to decide where the business needs to invest, or some other decision maker really, really doesn't have time to read through 40,000 lines of code in several languages to find out how a feature works.
For example: one of my first jobs was with an established big brand with many years of legacy data and organic "enterprise" systems, integrating data produced by an AS400 green-screen application into VB (on a Windows box) by copying (via FTP on a SCO box) a fixed-width text file produced by a shell script on the AS400, and parsing it so we could put it into Oracle for processing by a C++ application with API hooks into a Nortel Meridian coms system. When an outbound call goes to the wrong number, where's the bug?
Even if I'm reading _my own_ code 6 or 36 months later, I'm much happier if I've logged the checkins correctly so that it narrows it down to which dozen or so of many thousands of commits touched a feature. Whenever I've had to track down someone else's bug, or tried to justify the technical justification for some business decision the system makes, or tried to write high level progress documentation (think changelog for senior managers), the commit messages make the difference between it taking two weeks and taking two years (i.e. never happening).
It's easy to think, in the post-codial glow when you're fresh from the zone, that there's no way this code isn't absolutely obvious. I've been that guy. I've also been the guy that cursed that guy for making it hard to find the needle in the haystack. I've even been both guys separated by 18 months. Commit messages can make the difference between getting it done in 20 minutes, and looking at "code that is well written, in good style using sensible variable names" for a solution for two days.
The parent comment nails this. These guys who thought "my code is clear therefore self-documenting" were some of the worse system designers and myopic thinkers in the company. What's worse, is this attitude usually extends to "my code is simple and therefore doesn't need to be tested."
Documentation has multiple purposes, and multiple audiences, and a good static type checker can't do anything for most all of them.
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.
/* standard quicksort on foo before we make our choice below */
That hardly seems like insanity to me.
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.
(A real-life example would be a function that outputs an image in JPEG or PNG and takes a quality parameter. I notice that within the same library often one type of image wants 1-100 where another type wants a different scale, like 0.0 - 1.0. The parameters have the same name.)
This is not something that can be checked by most type systems. Therefore it needs to be in the documentation.
[...]
> This is not something that can be checked by most type systems. Therefore it needs to be in the documentation.
Or, alternatively, we need better type systems. (Of course, it can still be in "documentation", just documentation that can be automatically generated from code that is also given real effect by the compiler, and thus documentation that can't get out of sync with the implementation.)
Do you write/have a technical spec? I think that's what you are describing. If I first and only write the comment, there can often be a disconnect between what the code does right now and what it would ideally do once I'm finished. On the other hand, a spec plus an accurate comment keeps everything in order.
I have not had much trouble with the comments diverging from the final implementation of a piece of code. But I have forced myself into a habit of re-reading through the documentation regularly once I've committed a chunk of new code. Just to ensure it all still does what it says on the tin. This takes extra time, but together with learning how to write decent commit messages, this has helped me keep things sane and organized.
I was hoping this was going to be about the real "documentation fallacy:" 'Documentation tends to be of low quality, therefore it is best to avoid writing much documentation.' One common instantiation of this is "thorough documentation is bad because it will inevitably fall behind the code and be inaccurate."
People fall into the trap of assuming there is something inevitable about bad docs. Yet they never assume there is anything inevitable about bad code, even though most of the code in the world is, objectively, complete shit!
It helps to start thinking of all this as one and the same. No single part of it is more or less important. If you are writing code, you are writing documentation, you are doing correct and thorough error handling and you are producing consistent and relevant tests. There is no difference.
"Explicitly writing out the intention of a piece of code in plain English often makes the concept much clearer in my brain"
I think is critical for me. I actually write code by first doing a pseudo-code pass of comments, where I just write the flow of what I think the code should be doing. Then go back and fill in the actual functionality behind the comments. Naturally, its not always perfect on the first pass, but you just mod the comment thought process to update your approach, and then refill the functionality. As a programmer, you can then skim down through sections just checking what its "supposed" to do, whether you're a newbie diving in, or the original writer who's just needing a refresh.
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.
Higher level documentation - classes, packages, groups of packages - makes the project much more approachable. It answers the question "Here's a 3 levels deep hierarchy - where do I start, how are the pieces connected to each other?"
Documenting classes is fairly common, but only the public API. I'm not only interested in how to use the class, but also how does it work internally, what is the inner architecture.
Often I find myself wishing that I could see things as a sequence diagram. I've never worked anywhere where functions were commented with useless English descriptions of the parameters and so on, so I don't really know if this is something that people really do. What I do wish I had was more high-level, visual representations of a system when I'm trying to learn how it functions.
http://golang.org/src/pkg/fmt/doc.go -> http://golang.org/pkg/fmt/
I've never really agreed with the whole "code should be just be obvious when read." The problem with any large set of instructions is that both the instruction, order, combinations, and other artifacts reflect the experience, background, and environment of the author. Two developers of largely equivalent experience and talent rarely come up with the same set of instructions for the same task.
Consider if I told you how an engine functioned as a means of telling you how to change a head gasket.
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!
All I know is, I help maintain a very large set of public APIs that my team is very resistant to changing, and yet somehow the docs are still out of date.
See 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.
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.
> 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.
Now sometimes one comes to the conclusion that an API is broken, so you have to modify the comments, and then modify the code, but there is a reason to do it in this order.
When you modify the comments you are modifying a set of promises you have made to other coders. This allows you to think through how this change is going to work and how it will affect other code out in the wild. Then, when you modify your code, it is going to be better.
But that can be a valid complaint as well. There is an undeniable cost of maintaining tests, and it shouldn't just be taken for granted that the cost is worth it.
The question is not whether to test or whether to document, but what to test and what to document.
> It isn't.
Yes, it is. Have done it myself loads of times.
Well, whether it is or isn't depends on how good the docs are and how well you write them. Yes, in many cases it can be easy to forget if the documentation is not woven in well enough.
> All public APIs should have documentation, even if you believe it's obvious what they do.
As a note part of the function of such documentation is to establish standards for what is acceptable in terms of expected input and output handling. What this means is that if documentation defines the code contract, then the first thing you look at when debugging is the API's documentation. Then, if it matches what you are doing, you might dig deeper.
What this gives you is not debugging by comments (something K&R rightly hated) but asking which side the violation of code contract is on. If the documentation doesn't match what you are doing with it, then the violation is on your side. If it does, then the violation may be on the API's side. The goal here is to define where changes can most productively be made.
> Because there's other code in the wild that relies on the behavior that you promised.
That's exactly right. More specifically the API documentation is the promise.
> 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.
The thing is it took us a long time to get our documentation approach right in LedgerSMB. It was a struggle that really only I think reached something I am happy with 5 years into the project. A lot of our public SQL API's are not documented actually, because they are dynamically discovered at run-time and are minimalistic (and consequently the developer contracts far more vague than the API conventions, so it isn't always clear what belongs in the documentation since it is all dynamically looked up anyway), but our Perl code is very well documented and I am very happy with that.
For the SQL though, it's written with documentation generation scripts in mind and therefore the question is what you can document on top of what is already there in the system catalogs.
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.
X for its own sake is rarely good.
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.
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.
But consistent naming does not help with the "optionality" of parameters.
Just start passing a single object parameter or using the arguments object and force everything into the documentation. Then it'll be just like 90% of libraries that depend on jQuery, especially once the code has been patched, updated, and maintained a year beyond the documentation.
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.
Just one simple (real life) example:
public String convertText(String text) {
return text.toUpperCase();
}
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
Sometimes comments are worth the cost, but they should be a fallback to a fallback - ideally, the code should be self-explanatory. If that's not possible, unit tests should explain the usage and functionality - they're better than comments because the build system enforces that they're updated when the code changes. Only if you can't do that either should you resort to a comment.
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.
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.
In general, if you have to jump into every method call to understand a method that calls other methods, the names are bad – probably too short and don't state intention.
But I put one-liners in a function when the one-liner is hard to read or too error prone (missing a detail won't lead to a compiler error, but to a bug).
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.
But if it had a specification comment added, it may be perfectly justified.
Remember, in programming, there's no problem that can't be solved by one additionnal level of indirection.
Here we have one level of indirection. What's not clear, is what problem it solves. This is what the comment should tell, or better, the name of the method. But perhaps we're in a context where converting things is the natural thing to do, and in this specific case, the convertion of text is a mere upcasing. Probably the conversion of numbers or the conversion of arrays will involve more work. Notice how I imagine (but leave unwritten) some specifications to justify this code. In a program those specifications should not be left unwritten.
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.
I am interested in examples of companies that get this right.
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.
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!
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.
`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
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.
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.
I got it from context, obviously, but can you explain this turn of phrase to satisfy my curiosity?
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.
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.
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.
And, in my experience at least, very few times the comments are out-of-date with the code. If that's the case, once is detected, it should be treated as a bug. Fix/remove the comment.
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?
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
And what's to stop you from putting the comment about race conditions in the Doxygen-style comment?
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.
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).
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).
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 ;)
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.
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.
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");
Please downvote me again.
But agree often documentation older than code. Its very fast older and add many noise.
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!
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.
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...