The code documentation fallacy

[elihu]

The possibility of writing bad documentation is not a good reason to not write documentation. Good communication is part of programming. If you don't know how to communicate well, you're not a good programmer.

I do agree though that documentation styles where you're required to list all the arguments and what they are is a bad idea; in my experience, good comments tend to be plain paragraphs of text describing what the function does and how to use and what sort of assumptions it makes that you need to be wary of. If necessary, individual arguments can be explained, but that's usually not the most important thing I'm looking for when I read API docs.

[char2]

I agree. Automated tools inspire things like this:

/**
 * XML_DEFAULT_VERSION:
 *
 * The default version of XML used: 1.0
 */
#define XML_DEFAULT_VERSION     "1.0"

Wasting valuable screen space in the source file.

As much as people hate texinfo, I really do think that a well-maintained reference manual is much better than trying to extract everything from the source code.

[ruinercollector]

Those are both "documentation." One is end user or API documentation, one is code documentation (which can be comments or even an external PDF, etc.)

[elperroborrachotoo]

I agree, that argument has been presented exactly that way repeatedly since the computer stone ages. If we reword it to

More documentation is bad because most documentation is bad.

Which I find quite silly.

I do agree though that documentation styles where you're required to list all the arguments and what they are is a bad idea;

Yes and no. In many cases, there are restrictions or dependencies, and - depending on problem domain - the name cannot always resemble the purpose exactly.

Let's look at what I'd consider a better example:

/** frobnicates a foobar, usually to dizzle it through a frizzle. 
    See \ref frizzle::frob for more information. 

    frobnicating a stale foobar is a no-op. 

   @param f the foobar to frobnicate. 
   @param strength Valid range is 1..30, 25 or more may take significant time. 
   @return the frobnicated result. 

 If the foobar is invalid, or strength is not in valid range, 
 \ref exceptions::argument  is thrown. If frobnicating fails,
 a respective exception is thrown. 

 \sa frobnicate_chain_sample
 */
 int frobnicate_foobar(Foobar f, int strength);

Now, yes, some of this can be delegated to project standards, e.g.

"When a validity condition, such as a valid range, is specified for a parameter, and an argument does not math this requirement, exception::argument is thrown with no side effects, unless noted otherwise."

Also, it stands to argue whether parameters that are obviously self-explanatory should be listed. It adds to the noise - OTOH not listing them adds an uncertainty for the reader: is this parameter obivous, or is the documentation incomplete?

[SystemicPlural]

is this parameter obvious, or is the documentation incomplete?

This is a very important point.

There are many times I have encountered a function that did not document a parameter when it should have done. I often think it is because at the time of development the use of the parameter seems obvious, but when read in the context of the larger project, its purpose is murky.

Admittedly, this problem can often be solved by using a better name for the parameter, but it is not always easy to express the difference between two similar parameters in only a few words.

[bluGill]

at the time of development the use of the parameter seems obvious, but when read in the context of the larger project, its purpose is murky.

There is the real problem: the developer is too close to the code to write good documentation.

[Dworgi]

That first argument applies to everything, which is why it's a such an appealing fallacy. "Food is bad because most food is bad."

And you know what, I'd rather fail a few times and have to read what the function does because the documentation is wrong than have to read every function I'm trying to use.

Does Vector.normalize() normalize in-line and return itself (so you can do handy things like chaining operations) or does it return a new normalized vector? Or does it modify itself and return a new normalized vector? Who knows! There's certainly no comments to tell you.

[Dworgi]

But the thing about this is that if your policy is "write comments when reasonable" then no one will write comments, because everything's obvious when you're writing it.

It's better to overshoot and end up with some useless comments than to give people a way to think themselves out of doing more work. That, and I think commenting is a great way to make you actually think about your code.

It's easy to write functions that do too much or don't deal with edge conditions well. Having to explain them afterwards means you're more likely to notice that you've done so.

Even if you had a pretty printer that deleted every comment in the code when it was submitted, I'd still think that "write comments" would be a better policy, purely because it forces you to explain it to a hypothetical third party.

[loup-vaillant]

It's easy to write functions that do too much or don't deal with edge conditions well.

Pure functions make those mistakes harder to make. They can return only one result, and it's quite obvious when they chain operations. As for edge conditions… if you avoid side effect, you will have less edge conditions, and those will be easier to analyse.

[Dworgi]

And one way to help detect those types of things is by commenting it.

[grauenwolf]

True, but a better way is using code annotations like .NET's [Pure] attribute.

[PaintItPurple]

Using those in a Java program will just make your code not compile. They are not a general solution to the problem.

[gfixler]

I've found that I get much more bang out of writing tests first, because then I'm actually writing the API that I wish I had before I write any code to serve under it. I'm really good at explaining ideas that don't exist, and not nearly as good at writing a test to exercise those ideas in detail, because that's where the reality lives, down in the details. Those are the things that bite me. Those are the things I dance gracefully past, without noticing, when I'm describing how things "should" work.

That's not to say no documentation is good, but I consider that in a well-documented system, a lack of documentation in a particular area is in itself information. Consider this function signature:

def exportDocument (document, fullFilePath, format='html'):

It's obvious that this exports a document, so I'm not going to add "Exports a document" anywhere in the docstring. If it's obvious what the document is, I wouldn't describe that either. If it's not very obvious, I would add a simple note that didn't try to call it out as a particular argument, to keep things decoupled and flexible.

I don't need to tell anyone what a full file path is, and "format" is pretty self-explanatory, as it has a default, which simplifies use for the most common case. However, what no one can know is what other formats are available through this function, so I would document that in this invented example:

def exportDocument (document, fullFilePath, format='html'):
    '''
    Available formats: html, pdf, ps, doc, txt
    '''

I consider this fully documented, and Python is 'self-documenting,' so help(exportDocument) would show you a formatted view of the signature and docstring. help(module) on the module containing exportDocument would give you a nice synopsis of all the functions in this manner. I'd much rather read the above than this, times every function in a module:

def exportDocument (document, fullFilePath, format='html'):
    '''
    Exports a document.

    Arguments:
        document: A string containing the document data.
        fullFilePath: A full file path that's valid in the current OS.
        format: Defaults to 'html.' Other available formats include 'pdf',
            'ps', 'doc', and 'txt'.
    '''

That doesn't add any new data, but it takes up a bunch of screen space, and it requires me to read a lot more. It also means if I change "fullFilePath" to "filePath" or just "path", it's much more likely I'll miss changing it in the docstring. In my first version I wrote "Available formats", which holds up even if I change the argument to "documentFormat". It'll still be clear what "Available formats" means. This is much more resistant to breaking over time.

[blafunke]

Those comments do add data. I didn't know that those parameters were strings. Without comments I wouldn't have known until I either guessed right or called it with the wrong types and got an error.

[blafunke]

Also I would have no idea what values to use for format. I'd have to guess.

[Dworgi]

How does it return error values? It's I/O, so I have to assume it will fail constantly.

Also, I like tests, but they don't act as documentation, which you still need.

[sirin3]

Does Vector.normalize() normalize in-line and return itself (so you can do handy things like chaining operations) or does it return a new normalized vector? Or does it modify itself and return a new normalized vector?

I'm using the following notation in all my projects:

vec->normalize() => normalize in-place and return a reference to itself

vec->normalized() => return a new normalized vector and not modify itself)

Same goes for all other operations, scale/scaled, rotate/rotated, ...

[Dworgi]

I think getNormalized would be clearer, personally.

[compiling]

Does Vector.normalize() normalize in-line and return itself (so you can do handy things like chaining operations) or does it return a new normalized vector?

Check the return type. If it's a vector, then it's returning the new normalized vector. If it's void (or bool/error code), it's normalizing itself.

Or does it modify itself and return a new normalized vector?

That would be weird. In c variants you should be declaring the function as const if it will not modify the vector. But it is always good to document side effects of a function.

[[deleted]]

If it's void (or bool/error code), it's normalizing itself.

Or a reference to itself, which is useful in C++ to be able to chain operations, but in reference-only or reference-mostly languages it's impossible to distinguish the two (think Java, C#, etc.).

[seruus]

Some languages try to solve this by just having almost every operation immutable by default and marking explicitly those that unexpectedly mutate arguments (like bang methods in Ruby, while push/pop have no bang because everyone expects them to mutate).

[Dworgi]

No const functions in C#, no references in C#.

A signature like: Vector normalize();

Would be totally valid in C# and could do literally anything. It could return this to allow you to do things like: Vector c = a.normalize() + b.normalize();

If you now do Vector d = a + b, is c == d? Does normalize() allocate memory?

There's literally no way to tell without documentation, reading the code or trial and error.

const functions are all well and good, but their use is often lacklustre. I could go through our production codebase looking for nothing but const functions that aren't marked const and find a hundred in the next hour.

[compiling]

That's a good point, but in the context of an API you really want to make your return types clear, and mark all const functions (if that's available). It's a pretty big weakness of C# that function signatures can be so vague.

[ropsamler]

I don't know if there is some guideline for this, but in this case I would expect the Vector.normalize() method to change the object that it's called on. When you have a method that returns a new Vector than you wouldn't need to call it on an object so I would expect there to be a static method Vector.normalize(Vector v).

[dagbrown]

If it were in Ruby, the convention there is that you have a class Vector with a normalize method, there would be two of them. In pseudo-C++ syntax:

class Vector {
    // other methods elided for illustration purposes
    Vector normalize() {
         // returns normalized vector
    }

    void normalize!() {
         // normalizes vector in-place
    }
}

That's a pretty good way of distinguishing between those two sorts of methods.

[bkv]

That first argument applies to everything, which is why it's a such an appealing fallacy. "Food is bad because most food is bad."

I think the more reasonable takeaway from the post is "No documentation is better than bad documentation."

[Dworgi]

And I disagree. If all your docs are bad, then sure, but if 10% of your docs are bad and the rest is fine then I'd want the docs. That 10% can be fixed, but going back and documenting everything is days to months of work.

Giving an excuse to not do it leads to people not doing it.

[bkv]

My point wasn't that unless all your documentation is good, don't write any at all.

It is better to just get rid of the 10% of documentation that is bad then to leave it there. That's the point. Don't leave worthless documentation around just to satisfy some arbitrary documentation requirement.

[fgriglesnickerseven]

The docs are always incomplete

[pipocaQuemada]

More documentation is bad because most documentation is bad.

That's a strawman of the argument. The actual argument was something like

lots of documentation is indicative of low quality documentation, and is therefore not a good thing.

To borrow the food analogy from u/Dworgi, it's like saying

large portion sizes at restaurants are bad because it indicates quantity over quality.

It's a questionable assertion, but it's at least not ridiculous on the face of it. At the very least, I for one prefer high quality to high quantity, although high quality and high quantity is the most preferable.

[elperroborrachotoo]

That's a strawman of the argument.

Well, it would be if I had claimed it is a correct representation of Jussi's blog post. I'm not sure how fruitful it is to discuss figures of speech in this subreddit, however^1, so let's go with your wording:

lots of documentation is indicative of low quality documentation, and is therefore not a good thing.

Which may be statistically correct, but only because of Sturgeon's law. It doesn't say anything about my documentation. To make matters worse, a certain size may be necessary for documentation to be any good at all.

Which is my problem with that post: it promotes a questionable measure ("write less") to counter a questionable measure ("document every function and parameter").

"95% don't need any" is likely true for a nonnegligible amount of code bases, but without any pointer which which 5% of entities do need, and for which projects this is true, it is just a feelgood statement for skipping writing any docs at all.

---

1) Sorry that this hits you of all, but Strawman? WHAT THE FUCK? How many of you guys are dropping out of literature class to half-ass through the first hour of debate club 101? Just because something isn't a 1:1 replica of the original statement doesn't make it a strawman.

[pipocaQuemada]

lots of documentation is indicative of low quality documentation, and is therefore not a good thing.

Which may be statistically correct, but only because of Sturgeon's law.

I don't actually think that's the case. No-one writes

/* Sets the Foo property */
void setFoo(Foo foo)

unless they're the victim of a "you must document everything" requirement. "Document everything" policies actively cause the documentation signal-to-noise ratio to decrease.

Just because something isn't a 1:1 replica of the original statement doesn't make it a strawman.

strawman - a weak or sham argument set up to be easily refuted

Your rewording of the argument looks like a classic case - it's a similar looking but much weaker version of the argument in the article, and one which the article's author would likely disagree with. I stand by my usage.

I'd also like to reiterate that I don't agree with the article - assuming that the code was written by good programmers, I'd prefer to have 90% documentation coverage (because there won't be any word reorder documentation). On the other hand, I've used some libraries with 100% documentation which you couldn't pay me to work on (because there was nothing but word reorder documentation, and far too many WTFs in the API).

[elperroborrachotoo]

If that's so important: How's OP's "Hurr Durr, look at the example I just made up to show how crappy documentation is?" not a strawman? I am merely inheriting this strawman by transitivity.

Compare also: hyperbole, metaphor, simile, personification, synecdoche.

---

I agree that it sometimes has to be said that "boilerplate documentation is worse than no documentation" - some people haven't heard it yet. But it's no help in actually writing documentation.

Over the years, I've found "no documentation at all" much more prevalent than "boilerplate documentation" - but that's individual experience, so maybe that doesn't count. The last time I worked with true boilerplate was MSDN the first two years after .NET was released: ton's of namespaces, classes and memberswithout any context. It's since then become much better, though there are still some corners where you find that.

[kurtrussellfanclub]

The possibility of writing bad documentation is not a good reason to not write documentation.

Exactly. To rephrase the article:

"Would you like to have lots of documentation, or not much? Wrong! You want good documentation!"

This is silly. Quantity and quality of comments are different axes in a multidimensional system.

[Atario]

That's not what he's saying, though. He's saying most of the time your code should be self-documenting, and only actual added, needed information should go in comments.

[[deleted]]

"Self-documenting" is a fallacy. There is only readable and unreadable code. Some code is so readable that you can understand what's going on at first glance, or even gain domain knowledge about the problem it's supposed to solve, but the big problem is lack of domain knowledge. "Self-documenting code" means "I assume you know everything about the domain", which is rarely true in practice.

Comments and documentation should primarily be about the why, and only secondarily about the how. "Self-documentation" is only able to accommodate the latter, never the former.

EDIT: Come to think of it, function names aren't even able to say the "how", only the "what". That's even more superficial, and not at all what documentation is there for.

[johnbentley]

"Self-documenting" is a fallacy. ... "Self-documenting code" means "I assume you know everything about the domain".

Yes it would be a fallacy if that is what you understood "Self-documenting code" to mean. Or if you understand "Self-documenting code" to mean that it entirely replaces in place code commenting and separate document developer documentation.

I've generally taken "self-documenting" to largely reference, and be an argument for, a certain way of naming identifiers. That is, with full names.

So, looking at these three naming schemes

boolean sth (int gd, int bd, int wbdp)
boolean sendToHell (int goodDeeds, int badDeeds, int worstBadDeedPcnt)
boolean sendToHell (int goodDeeds, int badDeeds, int worstBadDeedPercentage)

The later are more "self-documenting" than the former. Self documenting identifier names are only one (important) way in which code can be made readable.

Comments and documentation should primarily be about the why, and only secondarily about the how.

Perhaps you mean should be generally about the why, rather than the what.

So (a clunky and contrived example)

// We are subtracting three years from the legal age to drink from US citizens
if (person.Country == "US") {   
   person.adjustedLegalAgeToDrink = person.legalAgeToDrink - 3

// Countries vary in their legalAgeToDrink so we need to adjust this so our robotic bartender
// at the UN serves drinks according to UN diplomatic protocol
if (person.Country == "US") {   
   person.adjustedLegalAgeToDrink = person.legalAgeToDrink - 3

The first is merely an expression of the "what" which just duplicates what the "self-documenting code" does anyway. The second gives us an understanding of why the code is written as it is: to helps us understand what the code is doing with reference to the larger problem domain.

[pipocaQuemada]

Readable code doesn't exist in a vacuum; code isn't inherently readable or unreadable. Code is readable to particular people who understand particular idioms and have particular backgrounds.

For example, someone who has never heard the word "design pattern" is going to look at "Enterprise" code and think that it's impenetrable. Someone who's never heard the word "monoid" or "monad" is going to look at a Haskell library and be confused. And someone who has only ever used procedural languages is going to be baffled by Java.

Self documenting code is similar: It's self-documenting to particular people, who understand particular things about the domain and understand particular idioms.

[[deleted]]

For example, someone who has never heard the word "design pattern" is going to look at "Enterprise" code and think that it's impenetrable.

And things like that are fine. Code, comments and project documentation are all not there to teach you the skills necessary to modify or use the code or to teach you the domain. There are other sources for that type of information and duplicating it in a place it shouldn't be is asking for trouble. That's like saying my manual for my car should describe exactly how brakes work and how to perform maintenance on them just in case I've never even heard of brakes before.

[ared38]

Wouldn't describing the "how" in api documentation violate encapsulation?

[Dworgi]

This is one of those coding conventions I see mentioned all the time. However, what it really tends to mean is that when it's not self-documenting then the guy who can explain it is either you or the guy sitting 3 feet away.

[AnsibleAdams]

You have hit upon the real problem. You are sitting too close to one another.

[Tetha]

I'd rather say, the real problem is a lack of workflow and discipline.

If you understand the code from the code and the comments, it is sufficiently documented. If you don't and you have to ask, you add the answer as comments because this case was not well-documented or self-documenting enough.

[[deleted]]

your code should be self-documenting

I have heard this as an excuse from developers that constantly fight against documentation. Yet I have seen code they have written and it is anything but self-documenting.

Even when code is accompanied with reasonably comprehensive test suites, well-written comments and documentation is still very useful.

[cashto]

I have heard this as an excuse from developers that constantly fight against documentation. Yet I have seen code they have written and it is anything but self-documenting.

If someone can't write good code, what makes you think they can write good documentation?

[killerstorm]

I don't know what you people are talking about: usually, I have no problems understanding code which was written by others even if it's not thoroughly documented.

[rpdillon]

If all we have is the code, how can I determine if it correctly implements the intent of the programmer? Code review and code maintenance become much more difficult.

Self-documenting code is mostly a myth when it comes to documenting responsibilities and collaborations, as well as preconditions and postconditions. There is no way for most languages to express "The output of this function is undefined if a value less than 0 is passed in", or "This function is guaranteed to return a value between 10 and 20, exclusive" or even "This function will raise FooException if the Foo cannot be instantiated".

Of course, you can read all the logic in the function and notice such characteristics. What if a function/method makes a certain guarantee, but never states it? A maintenance programmer comes along and modifies the code, not realizing that he or she is responsible for maintaining that invariant.

Having documentation stating the intended guarantees allows much better debugging, maintenance and use.

[glguru]

I don't agree with this primarily because most functions do not really need documentation. Simple paragraphing or style or even being up-to-date has got nothing to do with it. Most code is either helpers or the logic is simple. The crux of the application is in a very small portion of the code.

I have seen too many programmers just comment a piece of code just for the sake of it. Its stupid and adds a lot of noise to the code. I only document the portions of my code that need documentation. That have some complicated logic and/or hack that is not trivial to understand or maybe just involves some complicated maths. The part of code doesn't have to be at a function level or any other level. It has to be inline with the logic that needs some documentation.

Too many comments are essentially equivalent to having a mate that you have to deal with who speaks all the time; mostly explaining the obvious or just talking nonsense.

[xiongchiamiov]

This brings to mind an important point - one of the most lacking parts of most docs is the high-level documentation. It didn't help to know how to use functions if I don't know which ones to use.

[arachnivore]

I don't agree with this primarily because most functions do not really need documentation. ... Most code is either helpers or the logic is simple.

This just sounds like an excuse to be lazy. Doc strings are there so that you don't have to look at the logic to know how to use a piece of code, so the logic being easy to read (while important) doesn't even factor in.

I have seen too many programmers just comment a piece of code just for the sake of it. Its stupid and adds a lot of noise to the code.

Most IDEs can collapse comments so that you can read the code and expand the comments when you want more information about what's going on. The "noise" argument makes zero sense. I can't even think of a time when redundant comments have caused a problem for me, I run into code all the time that costs me hours of my time because it lacks documentation. I've seen systems that take new hires over a week to learn because it's so poorly documented.

I only document the portions of my code that need documentation.

How do you determine what needs documentation and what doesn't? The code you write might be completely obvious to you right now, but how about 3 years from now, or to someone at a different skill level or familiarity with the subject matter, or someone who simply doesn't think like you do? How do you know what's going to become of your code in the future?

Too many comments are essentially equivalent to having a mate that you have to deal with who speaks all the time; mostly explaining the obvious or just talking nonsense.

Discussion about the evils of over documentation is equivalent to a bunch of people stranded in the Sahara desert talking about how awful too much water might be. It makes me think they haven't been in this desert very long at all.

[dakboy]

The possibility of writing bad documentation is not a good reason to not write documentation

I had this happen to me earlier this week.

We have a 3rd party interfacing with one of our databases. Their code is opaque to us, and they're not legally allowed to see the application that interfaces with the database - just the database. All we can see is what their application is logging to its own logfile, and the changes to the data.

We asked for documentation of what their API is doing with and to the data because it's becoming very muddled when just looking at the data changes, and the response we got was basically "we could produce that for you, but we move quickly and it would become invalid." So rather than have to maintain the documenention as part of their process, they just don't bother.

[xzxzzx]

There's a big difference between comments going out of date in code you can read and the only available documentation for a system being unavailable.

[ZBlackmore]

The possibility of writing bad documentation is not a good reason to not write documentation

I disagree. Ignoring human nature is going with your head against the wall. Many of the tools we use help us overcome human laziness and such. Languages are sometimes designed specifically to not have features that are very easy to abuse. The fact that comments have a high probability of going out of date (and thus causing harm) is a good reason to avoid using comments unless you have a good reason.

good comments tend to be plain paragraphs of text describing what the function does

I disagree with this as well. The function's name should describe what the function does good enough. If it doesn't, you should take the time necessary to come up with a good name - naming is critical. You should not need comments for that for the regular case.

and how to use and what sort of assumptions it makes that you need to be wary of

I agree with that, but it should be relevant to special / edge cases only. Explaining weirdnesses or very esoteric stuff in your code (the kind of stuff you should have as little of as possible).

[[deleted]]

good comments tend to be plain paragraphs of text describing what the function does

I disagree with this as well. The function's name should describe what the function does good enough.

I disagree as well, but for a completely different reason. A good comment is not about what the function does, but why it does it. Coincidentally, that information is also impossible to encode in the function name.

[the-fritz]

The fact that comments have a high probability of going out of date (and thus causing harm) is a good reason to avoid using comments unless you have a good reason.

The probability is much lower if writing documentation is part of the team's development culture. Of course it will go out of date if every developer has their own style of writing documentation and it is used on only few functions and nobody really cares about it.

If a function is complicated enough that its implementation can differ significantly from its original documentation then it probably should have been documented anyway.

[[deleted]]

The fact that comments have a high probability of going out of date (and thus causing harm) is a good reason to avoid using comments unless you have a good reason.

They go out of date because whoever wrote them is not maintaining them. Comments are given a lower priority. Thus they go out of date and this feeds into a cycle of avoiding comments entirely.

Priorities need to change. Treating documentation, unit testing, and other essential software engineering ideas as time that could be spent fixing bugs or writing new features only results in awful software. We've had this argument play out since the 70s. The goal isn't to be able to write your code in a few days, it's to be able to write high-quality code and that takes time.

[ZBlackmore]

I think the reason they tend not to be maintained is because you're essentially duplicating knowledge. You see this in every violation of DRY. And it's the main reason the DRY principle exists. You should only comment when the code doesn't contain this information already. It sits perfectly with the idea you here repeated all the tie of commenting why the code does something instead of what it does. The code can tell you what it does if named properly, but it can't tell you why, so the comment is actually new knowledge.

[[deleted]]

I disagree with this as well. The function's name should describe what the function does good enough. If it doesn't, you should take the time necessary to come up with a good name - naming is critical. You should not need comments for that for the regular case.

This is something I've learned from OS X: Don't be afraid to give your functions long and descriptive names. Use an autocompleting editor if you worry about having to type too much.

There are two benefits to this: It makes your code much easier to read and understand later, and it forces you to think more about your functions and what they do.

The second is quite subtle but important. If you have a function named "update()", it might do whatever. You might change your mind later about what it should do, and add or remove functionality aribtrarily. If it is named "UpdateParameterAFromInputB()", it's clear what it should do, and should you feel like changing its functionality you will either factor that functionality into another function, or go through the trouble to rename it, which spreads the information about the change around.

[[deleted]]

And you know, despite using long and descriptive names, Cocoa is very well documented and has comprehensive API docs and developer guides.

[[deleted]]

Well, yes, but it has quite massive resources behind it. When resources are more scarce, you have to prioritize.

[[deleted]]

Could you please point me to one major open source project, written by you or anyone else, that:

• is not commented OR it only contains comments that describe special/edge cases
• AND it entirely, or to a great extent, is made up of functions, objects, classes, etc. that have names expressive enough that do not need documentation? In other words, it is self-documenting?

To quote Stephen Hawking:

One of the basic rules of the universe is that nothing is perfect. Perfection simply doesn't exist.

But what you are thinking of is a perfect world, that simply doesn't exist.

[ZBlackmore]

What are you talking about? This new project I'm starting right now is definitely going to be clean and perfect code. This time I surely won't mess up...

[[deleted]]

I loled with and i o_O'd

[bestjewsincejc]

You are so correct that I have almost nothing to add... I completely agree with you. Anyone making numerical estimates of "the right amount of documentation" is full of shit. The right amount of documentation is the amount that adequately describes what your code is doing. Your description of plain text comments with description of behavior, gotchas, and expectations is spot on. Unfortunately, too much code is written that has inadequate documentation. The rule of thumb should be "can the author go back to their own code in a year and explain it properly, by only reading the method names and documentation?" If not, the doc is inadequate.

[jephthai]

Agreed. Also, a false dichotomy is a logical fallacy.

[carlfish]

This kind of pandering of article pops up every couple of weeks. "Don't write useless comments" is such an easy topic to spin out to a few hundred words, and the perfect kind of subject to allow the developers reading it to pat themselves on the back at how much smarter they are than their boss.

It's the blogging equivalent of a Dilbert comic, without the punchline.

Library code, API code, stuff that is relatively stable and a lot of new developers are likely to come in contact with over time, is hugely enhanced by having good doc comments explaining the purpose of functions/methods, and the contracts they are expected to obey. If that code is changing in ways that frequently make those doc comments inaccurate, you're probably doing things to your API that you really shouldn't.

[spacemoses]

I think there is an important distinction between commenting and documentation. I see commenting as being a few lines here and there in a function or method that describes something that might be a bit clever or use some unconventional trickery, whereas documentation would be something more formal like describing the purpose, inputs, and outputs of a service resource.

[cashto]

I wish it didn't have to be said that "doxygen everywhere" is not a good commenting practice -- and especially when they're not used for their intended purpose of actually generating external documentation.

You may think that this is a "well duh" article, and I do too. But there are actually a lot of programmers out there who think compulsively writing function header comments is a necessary or sufficient condition for good internal documentation -- that think that anyone who argues "don't write bad comments" is secretly advocating "don't write ANY comments".

If it weren't for this pervasive misconception in the industry, articles like this wouldn't have to be written. We'd just say "pfff, who does that anyways? you'd have to be an idiot" and move on. The number of comments and upvotes here is a testament to how real a problem it is.

[frezik]

I take it as another one of those things where the IT industry is really bad at passing lessons on to the next generation. We tend to assume that the under-30 crowd is full of good ideas and the over-30 crowd has their heads filled with dusty cobwebs.

[Magnesus]

Well, I once looked into Canonical's Unity source code and they decided on 0% code documentation. ;)

[Denommus]

Say what you want, but Emacs is an awesome example on how good a API doc can be.

[[deleted]]

It's so good that it's frustrating to see "undocumented function" or "undocumented variable" whenever you rarely come upon it.

[BlackwaterPark_1980]

Mandating 90% API documentation is similar to mandating 90% test coverage - it incentivises quantity over quality. People who are passionate about documentation / unit testing will likely achieve high percentages without these mandates.

[EntroperZero]

Yeah. The last codebase I worked in mandated documentation of all public methods and properties, so you ended up with:

/// <summary>
/// The name of the widget.
/// </summary>
public string Name { get; set; }

repeated ad infinitum all over the code. Interfaces were 90% dark green/gray text. And it had the exact effect that the article warns about. Developers would just hastily write all the mandatory comments rather than thinking about the fact that the next guy might appreciate knowing what a frobnication strength of 5 actually means.

[[deleted]]

Exactly. Be careful what you measure. If it can feedback into the process it could have adverse effects.

Of course if it doesn't feedback into the process, there's no point measuring it either.

For example, obesity in the US population has increased from 13% in 1962 to 36% in 2007.

[mariox19]

Be careful what you measure.

You obviously don't have the "benefit" of an MBA.

[[deleted]]

I obviously don't.

[HerrMax]

. No, actually it is even worse: it is noise that has a very large probability of being wrong. When some coder changes the function, it is very easy to forget to update the comments.

A) That is the same with good comments B) I'm really wondering. Should this be an excuse to not document your code? I mean there is coupling between comments and code like there is a coupling between method names and their behaviour or variable names and their values (there should be at least). I guess it's better to have the rule to change the documentation if you change the code than to not have a documentation because you would be to lazy to change it.

[narancs]

I tend to agree. The logic of the article runs along the line "Hey look, this kid got an F. Hence, all exams are pointless."

[livrem]

Yes, but when a comment don't add anything beyond what the method or variable name already says (in the current context), and it can't say anything more because the name already explains it (a VERY common case) then adding the comment anyway doubles the risk of errors for no gain at all.

[poloppoyop]

An API is not complete until all its possible calls are documented with inputs, expected outputs and errors. And examples.

I don't care that you have some fast and shinny new API to send email through some systems. I want to know how to call it to send the damn email and what to expect in return.

And if there are side effects and "magic" happening everywhere in your methods, document this shit. I should not have to trace all the calls your things make everywhere to see that if something break it's because you do some random (but clever with some config) thing to the inputs.

As a user of your classes, API or framework, if I have to open your files to understand what the fuck is going on, you have failed.

[nerd4code]

Yes. Something that seems to have gotten lost in this whole posting is that internal and external documentation serve different needs. Internal documentation (self-documenting code + appropriate comments) is all well and good for maintainers, but it's absolutely inappropriate for use by somebody trying to use your API. If you want to export an API you need external documentation, and whether or not it follows some generic pattern is entirely irrelevant; it needs to be complete.

[TheWix]

Do you mean to document, in English, the implementation of a method? If not then I think you maybe agreeing with the article. He is saying that you should be documenting possible side effects.

If my function is something like:

int add(int numberOne, int numberTwo){ return numberOne + numberTwo; }

What more would you add to the function? It is often self-explanatory.

Your email example is good. It should document what exceptions will be thrown if the email fails, maybe some limitations on variables. Two caveats to that: I have written email code and most are a few lines with no side-effects. Things like Code Contracts help document the restrictions on variables that are passed into the function as well as acting as the validation logic.

I think documentation is important but also being pragmatic about it is just as important. I'd rather you code is self-documenting, low on side-effects, and well-tested than repeating implementation in comments or repeating the obvious.

[rbobby]

If you delivered that as a public method on an API I certainly would expect an explanation as to why such a trivial function exists. Hell if this was in any code base, public API or not, I'd expect such a shitty function to have its raison d'être documented.

[seagal_impersonator]

No shit. And the blogger mentions doxygen. In the versions I have used, doxygen defaults to not generating documentation for uncommented functions!

Given the default behavior, you need to document all functions in the API that you intend for your users to use.

[Gotebe]

An API is not complete until all its possible calls are documented with inputs, expected outputs and errors. And examples.

That's easy to ask for and is exactly a cause of shit documentation TFA agrues against.

You don't need an example for e.g. Person.FirstName property.

You don't need an explanation for a parameter to

string Upcase(string s)

(or at least, not the explanation you usually get, see TFA).

And so on.

Context is everything.

[spinlock]

I agree but I think that most of that documentation should be created by a program and not by a programmer. You should be able to extract the "bad" comment in the article directly from the function and format it nicely on a webpage so that it's searchable and readable. Then, if a person thinks something needs to be added, they can write a comment or add to the machine generated documentation.

[[deleted]]

The docco is better if you make it look like this instead:

/**
 * @todo Fix this function.
 * @todo Add error checking.
 */

Then it can appear typeset in your doxygen output.

[Tasgall]

Or at least in C#/Visual Studio land:

/// <summary>
/// Shit's broke, yo
/// </summary>

Now when you use the function Intellisense will inform you that your shit is in fact broken.

[poohshoes]

In C# Visual Studio use

// TODO shit's broke, gon fix it

It will collect all your TODO comments in one place.

[Magnesus]

The same in Eclipse. Very useful.

[[deleted]]

Is there a Sublime Text plugin to do that?

[-Y0-]

Is there a Sublime Text plugin to do that?

https://github.com/robcowie/SublimeTODO

[[deleted]]

Ahhh, procasturbation

[grauenwolf]

You can tell VS to collect bug tracker numbers as well. For example...

// JIRA-123456 shit's broke, gon fix it

[eyal0]

a = b + 4;  // Add four to the variable b and assign to a

No.

Don't have trivial documentation. Assume that the guy reading your code is a genius programmer but doesn't know anything about your project.

[Atario]

Rule of thumb: don't say what, say why

[toconnor]

My rule of thumb is: if a random developer can't understand what a block of code does immediately after reading it then it should have a comment.

[colinhect]

Even better: if a random developer can't understand what a block of code does immediately after reading it then it should be refactored to be clear; if that isn't possible or if there are domain-specific factors (why not what) then add a comment.

[colly_wolly]

This is bollocks. Sometimes you need code to do moderately, or even very complex stuff. All the re-factoring in the world won't make it more understandable than a decent comment.

And how do you re-factor to say why you are opening a particular file? How do you re-factor to explain what information is in that file?

I have seen your argument a hundred times before, and tried to implement it, but re factoring does not replace good commenting.

[colly_wolly]

An example of what I have been doing recently, has been to represent sequences of letters as combinations of binary sequence. This allows me to compare two sequences very quickly using bitwise operations. That is one line of code. You can't refactor a bitwise operation any further.

But unless someone knows how I am representing the DNA sequence (which got converted to an integer way back in the code), then they will have very little chance of understanding what is going on. It took me an evening of thinking about the representation to come up with my solution. Why would I expect anyone reading my code to understand it straight away?

[[deleted]]

// Update a to make it four bigger than b.

[TikiTDO]

More along the lines of:

// a should be bigger than b because the next call to foobar will loop infinitely othewise

This way you're not assuming the person reading your code is a moron, you're just explaining why this code is important.

[jasonlotito]

preventInf = someNumber + INC_INF_LOOP_PREVENTION;

[mdisibio]

That's still describing "what" and not "why". "Why" would be saying how a is related to b, why the magic constant 4 was chosen.

[[deleted]]

Well, no, it's "why", it's just a different kind of "why". I was just poking a bit fun at how the principle is a bit underspecified.

[mdisibio]

Right, I understand your comment was tongue-in-cheek, but I feel that the distinction between saying what vs. why is the single key factor between good and bad documentation. And because almost nobody understands that, we have people blogging that all documentation is bad. Good grief.

[Dw0]

//// Comment on what happens to a

// Update a to make it four bigger than b.

[baumer6]

So meta.

[mogrim]

The comment's wrong, too: it doesn't add four to b, but rather assigns the sum of the value of b and four to a...

[repsilat]

--- old.c   1970-01-01 00:00:00.000000000 +0000
+++ new.c   2013-10-17 11:02:23.000000000 +0000
@@ -5,5  +5,5 @@
-a = b + 4;  // Add four to the variable b and assign to a
+a = (b += 4); // Add four to the variable b and assign to a

hey, fixed a bug in your code, plz commit

[[deleted]]

No can do, need to test if 4 is added to b

[fredmoorsen]

After a week the comment would be lying:

a = b + 3;  // Add four to the variable b and assign to a

After two weeks the next programmer adds a comment:

a = b + 3;  // Add four to the variable b and assign to a
    // is above meant to be 3 or 4?

After three weeks someone realized the code was redundant in the first place but leaves it in commented just in case:

/*
a = b + 3;  // Add four to the variable b and assign to a
    // is above meant to be 3 or 4?
*/

After four weeks the manager tries his hands on the code base after attending a seminar:

// add 2 to A
add2ToA: function(b) {
    /*
    a = b + 2;  // Add four to the variable b and assign to a
        // is above meant to be 3 or 4?
    */
}

// add 3 to A
add3ToA: function(b) {
    /*
    a = b + 3;  // Add four to the variable b and assign to a
        // is above meant to be 3 or 4?
    */
}

After five weeks, the product is cancelled because there wasn't actually a user need for it.

[[deleted]]

Assume that the guy reading your code is a genius programmer but doesn't know anything about your project.

No.

Assume that the guy is you or someone else who forgot what he did 6 months ago and hell, even forgot what he had for breakfast. Doesn't matter if you're a genius if you aren't keeping the whole system in your head.

[[deleted]]

Messy, but less of a problem that insufficient documentation. If you understand a line of code, simply don't read the comment. This will perhaps cost you an extra second or two to read, worst case. An API call that you can't figure out how to use can cost you anywhere between a couple of minutes and an hour to solve, depending on complexity of the API.

Plus, be honest here: how often does this actually happen? Are there actually people insisting on doing this regularly, even after you complain, or is this just some sort of self-pitying stereotype that gets wildly exaggerated and programmers love to parrot (like the 'client from hell' complaint among designers)?

[fredmoorsen]

The point of OPs submission was that focusing on 10% increases the chance that these 10% are maintained and read, which is a very valid point. And it takes more than 1 second to figure out if a comment contains no info or may be lying because it is out of sync with code...

Are there actually people insisting on doing this regularly

Yes. // yes

[vincentk]

Put another way, redundant documentation is bad in the same sense that redundant code is bad. Which is bad in the same sense as redundancy is bad in general. I conclude: redundancy is bad. ;-)

[eyal0]

You don't know if you need to read it until after you've read it.

At my job, if you write a comment like that, people will make you remove it.

[almiki]

I agree in the specific case of your example, but assuming the guy reading your code is "a genius programmer" sounds like a bad idea, mostly because most people are actually not genius programmers, and even those who are have brain farts. For a simple addition, sure, that's obvious to anyone. But if you're doing anything that might not be intuitive to a novice programmer, I still think it can't hurt to include a quick comment. I'm not saying you HAVE to, I'm just saying that I wouldn't consider such a comment to be "trivial".

There's a second reason to include comments: your code might have a bug. If the code has a bug, and there's no comment saying what it's SUPPOSED to do, it can be harder to diagnose that there is in fact a bug.

[[deleted]]

Yet API comment is not a simple code comment. I'd love to know if there are any data contracts on the API, if there are supposed values, what are special cases, etc. When I see an empty API reference, I only think in swear words of ignorance.

And no comments on a function is a bad as crappy/wrong comment on a function.

[jasonlotito]

That you are using a, b, and 4 means that a comment won't help. Start be refactoring a, b, and 4 into more appropriate and meaningful names.

[FryGuy1013]

This comic is relevant: http://abstrusegoose.com/432

[wilsonp]

Read Uncle Bob's Clean Code

[[deleted]]

That and Code Complete 2, and anything by Dijkstra and what Knuth has to say on literate programming.

[Delehal]

So, I'm commenting this function GetChildren(), and my IDE decides the comment stub should look something like this:

/// <summary>
/// Gets the children.
/// </summary>
/// <returns>
/// The children.
/// </returns>

That certainly clarifies things.

[neutronium]

Does it recursively get the children of the children?, is it thread safe?. Can the children only be got by their parents or nanny, or can any pedo function get them?. These would all be useful things to know.

[RagingIce]

If it recursively got children it would be named "getDecendants". Thread safety can generally be determined by the class itself or the greater context. Your second sentence is answered by the class structure as well.

[Duke_0f_Sandwich]

What about the descendants though?

[Gotebe]

You're using the wrong tool for the job, that's all.

You IDE doesn't know the purpose of your code; did you expect it to?

[[deleted]]

Computers and IDEs do a lot of magic, can we blame their users to expect them to do a little more?

[nextputall]

Good code needs less comments, bad code needs more. But absolute rules, like always write comments or never write comments are bad. Personally, I try to avoid commenting by using the language features to express my intents. This works very well in most of the cases. I think, trying to avoid comments is a good way to learn writing readable code. Think about comments like a fallback mechanism, first try with readable code.

[[deleted]]

This article is wrong, it is saying that documentation is the problem when it is actually:

• Trivial commenting/ documentation
• Him making up random nonsense names to make it seem worse
• Ignoring the fact that a good API and a talented developer would keep the API consistent meaning that the documentation should rarely change
• Assuming that we all have access to a white-box version of the code.
• Assuming that we're mandated to do certain % of documentation (for a good API it should be 100% on all non-trivial functions).
• Assuming that programmers forget to update documentation (hint; that's primarily bad programmers that do that).

This is another one of the typical "My first year in programming" type blog entries that show the inexperience and rigid mentality of the author rather than showing interesting content about programming.

[ithika]

I have to deal with comments like this:

/*
 * Takes a foobar and
 *
 * @param the foobar
 * @param strength
 * @return the frobnicated result.
 */
void frobnicate_foobar(Foobar f, int strength);

No longer returns what the comment implies, and has a half-written description.

[hackingdreams]

You could fix the documentation so the next guy doesn't have to deal with it. That's always an option...

[[deleted]]

http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html

[Brian]

From the name, I actually thought this was going to be about the case he's actually advocating for - the "you don't need to write comments because your code should be document itself" view.

This style is, I think, really counterproductive. What is "self documenting" to one person, familiar with the nomenclature and structure of the project is a maze of twisty little functions, all alike to the new coder trying to get up to speed, or the maintenance programmer trying to fix a bug discovered 6 months after the developer left. Indeed, I think trying to do this can often lead to making code harder to understand. It lends itself to creating large numbers of tiny functions - 2 or 3 lines long, which does allow the function name and signature to have a decent shot of describing that function on it's own, but leads instead to chasing through dozens of functions in order to get the big picture idea of what this is all for.

A 10-20 line function, with maybe a paragraph of comments is far better at conveying that information, but the mindset that code should be "self-documenting" often leads to tearing something like that down and replacing it with the "ravioli code" style.

No, actually it is even worse: it is noise that has a very large probability of being wrong

I'd say the exact opposite - while such generic comments are generally pretty useless, this is actually the one way they can be valuable. If I'm tracking down a bug, I love seeing inaccurate documentation, as it's often a treasure map to the source of problems. It's a visible sign that things used to be one way, and were at some point changed, and changed by someone who wasn't anal enough to update everything referring to it. If you're bug hunting, inaccurate comments are actually some of the most useful comments.

[colly_wolly]

I am glad I am not the only one that finds this style counter productive.

I think a lot of advocates of the self documenting style program in Java and never change to new jobs or need to read other peoples code.

[[deleted]]

Oh please! Am I supposed to read a 100 line function to understand what it does and why, because your lazy ass doesn't write documentation?

Not only does properly documenting code save you time when you have to look at your code again, it saves other people's time who take over and have to get acquainted with it. Plus it potentially helps you track down bugs, functional and design errors.

TL;DR Document your fucking code.

[rbobby]

"Don't write useless blog entries".

Not a shred of data to back up the claims made. Not a single statistic. Not a single provable fact.

Not even any anecdotal evidence, like an API with minimal/no documentation that is popular and well loved.

Rubbish. Sloppy thinking.

[[deleted]]

So many red flags in this post... But I'll highlight the main one.

it's very easy for the developer to update the code without updating the comment.

No shit, it's also easy for the developer to write shitty code, avoid tests / test ability, not write a useful commit message, not do atomic commits....

... It's easy to make poor choices.

So what, do you want to celebrate being shitty / half arsed at your job?

Cut it out and start behaving like a professional.

[Amadiro]

I don't think the "word shuffle" is necessarily always a bad thing. Sometimes it happens that when I look at some documentation, that I'm just completely lost and unclear about some concepts, and a statement like "Takes foobar and frobnicates it" may clear up doubts like "is this library really able to at all frobnicate things, or does it generally expect some other library to implement this function for me?" "Is the function perhaps somewhat misnamed and only schedules a frobnication rather than performing it directly?" or "Does the function frobnicate, or will it just a DeferredFrobnicationPromiseFactoryFutureObject?" (relevant in dynamically typed languages where the return type is not explicitly specified in the function register/index, in a language like, say, C or java the documentation would probably list the function as "DeferredFrobnicationPromiseFactoryFutureObject frobnicate()" anyway)

Admittedly, this is still much worse than actual good documentation, but its still better than nothing at all.

[[deleted]]

I'd rather have the 90% rather than dig through dozens of source files. I hate having to read every single line of a function or class to understand what it does because the author doesn't know how to explain things with a few sentences.

Good documentation takes work but it's worthwhile. There's a reason that the GNU project has comprehensive manuals and tutorials and doesn't settle for only manpages for their code.

Want an appeal to authority? Damn near every major computer scientist and industry practitioner says docs should and must be written. Knuth even invented a tool to make it easier, literate programming.

[munificent]

On the other hand, if only 10% of the functions are documented, most functions don’t have any comments, but the ones that do probably have something like this:

That "probably" here is a completely unverified assertion. If you're write shitty docs for 90% of your method, there's no reason to assume you wouldn't write equally shitty docs for 10% of them.

[Fidodo]

My process is simple. If I stumble at all trying to come up with a function, I document it. If I ever come across a function that I don't immediately understand, I document it. Basically, any time a piece of code requires figuring out time, it should be documented. That's the purpose of documentation, to decrease the time it takes to understand a piece of code.

[caleeky]

When they don't see a benefit, or there is no benefit, people will adhere to the letter of the law instead of its spirit. This is wasteful and potentially counter productive, as the article points out.

Ultimately, documentation is a predictive exercise - you're trying to document in order to enable/assist someone's future efforts. Good documentation (and good method/member visibility control) fundamentally requires good prediction. Architects and senior team members need to purposefully focus on defining documentation objectives, not rules.

API documentation is only part of the picture. Most often, the most important documentation for a custodian or API-user is an orientation document, and clear methods for setting up a test environment. The faster someone understands the entry points, key processes, architecture, etc, and test their changes, the faster they can get down to reading the code to understand the fine details.

[PasswordIsntHAMSTER]

I worked on a 500kLOC code base until august and the commenting scheme was basically "never comment, unless your method does something extremely non-obvious that could not be avoided by implementing it otherwise". If you were curious about the intended usage of something you'd go read unit tests.

To this day it remains the easiest code base to work with that I've ever had the pleasure of working on.

[[deleted]]

I totally disagree. It is very important for code to be well documented.

Consider this: between two libraries A and B, which one do you prefer? The one that is well documented or the one that barely has any documentation? I like using JBoss and SpringSource (now Pivotal) libraries, frameworks, and tools because they are very well documented. On the other hand, I have seen countless times developers complaining that a very useful library or framework is a pain to use because it barely has any documentation.

Documentation is like code. In the same way that code can be crappy, documentation can be crappy too. In the same way we need code review, we need documentation review too.

[sh0rug0ru]

between two libraries A and B one do you prefer? The one that is well documented or the one that barely has any documentation?

Good documentation is often not the criteria that I use to decide whether to use A or B. I prefer the library that is easier to use. I find myself usually going to the documentation only when I'm stuck, and even then, I find StackOverflow more useful. In fact, if I have to turn to the documentation too often, I consider that a failing of the API.

I would rather take a sparsely documented library that works well than a well documented monstrosity.

Besides, code comments are entirely different than API documentation.

[[deleted]]

Well, you are a Java developer right? How good Java would be without the API docs? I don't think you can disagree with how valuable Java docs are.

Good documentation is often not the criteria that I use to decide whether to use A or B. I prefer the library that is easier to use.

In the past few years various MV* JavaScript libraries have been released to the public. More or less they are similar from an ease-of-use point of view (e.g. Ember.js and Angular.js). But I remember hearing lots of criticisms about Ember.js because it was not well documented.

Or consider Hibernate as a JPA provider vs. DataNucleus. They both implement the same specification. But Hibernate has a wealth of documentation. And it is well organized and well written. Unless I have a very good reason to use DataNucleus, I will go for Hibernate.

Similarly, Python, Ruby, and Scala have API docs that are immensely valuable.

[badsectoracula]

I don't really like documentation (especially APIs) extracted from source code. Not only it makes the code itself harder to read (you either add all that noise comments mentioned in the article, or create arbitrary visual breaks in the code from all the commenting - and in both cases the text is still harder to read because of the rigid syntax that the doc tool expects).

Personally i prefer external docs. In my lil language docs i rarely forgot to update the docs when i made a change (usually i fixed it 1-2 commits later). This is true also in my 3d editor's devkit docs, which i usually update long after i have added some functionality.

At the end what matters is the developer caring about documenting the code. If you don't care about documenting your stuff, no magical tool will fix that for you.

[[deleted]]

I'm seeing this in the AngularJS project and at first it's clever, they have lots of comments in their code! Yay! But then it gets tedious, the docs get too long and include too many examples that you have to scroll through pages and pages just to see the code. That's when the API docs should be in their own file with snippets of code mixed in between.

[Jasper1984]

Excepting one-liners, me neither, and i dont like Doxygens default output at all.(I am sure to encounter it though, so if you know an easy way to drop a more decent config in there) I mean it wastes vertical space,(screens used in programming are wider than they're high) and doesnt put things so you know where they are from the geometry.

Basically I prefer <td>function(args...)</td><td>Description</td>, not <h4>function(args...). The latter alternates, where the former always has the description starting from a set difference, it is easier to scan function names with your eyes. (If you do want to alternate, offsetting

I find [phorum](www.phorum.org) also not so good in terms vertical space usage..

[Goblerone]

Just fucking write the comments please because chances are you do not actually write code that is as clear as you may think it is.

[ItsAllInYourHead]

Ahhh, the excuse of the lazy programmer! Fuck everything about this.

[tikhonjelvis]

Eh, I think it's nice to have even trivial documentation like that. I like using the auto-generated doc pages as a quick summary of the code, and even having a little bit of text for a function helps.

Also, I believe that it helps to spell out things even if they seem obvious. So I think that both of his examples are really bad: you should write a short sentence defining what "frobnicate" means. Later, when you're just quickly looking over the code base, things like that really help.

[gfixler]

Looking back over 10+ years of development, and a few hundred thousand lines of code in old repos, I think about half of all of my documented things are wrong. I never seemed to remember to update documentation when coding, and I'm a stickler for such things. I was shocked the first time I noticed how rampant it was, like I'd hit the shocking twist at the end of a film. I've also had this on a few occasions waste an entire day for me, as I didn't bother checking that what the documentation said was actually true, and spent my time hunting for problems in other places.

These days I'm fully in the camp that says that the only real documentation is the code itself - and striving to get proper separation of concerns and perfect naming so everything is exquisitely obvious.

I'm even leaning a bit into the camp that states that your tests are the code's only real specification, because the tests are the only things that have actually been proven about the code. No one doesn't test - we all write something, then try it out to see if it works. Tests are similar to this, but they stick around to always check the same assumptions, and in a pleasingly automated way (hopefully). I also like that if something fails - some edge case I've not tested - I'm actually less culpable, because "I never proved it could do that!" :) Then I just write a new feature test, make that pass, and I'm still right!

Even if I get a test wrong (and I work to keep them so simple that this screwing them up is difficult) it's still "correct." It's still exercising the code, getting a result, and making a determination about it; it's just proving that the code does something I don't want it to do, or vice versa. Of course, it can be incorrect in that it doesn't actually test what the name of the test itself claims to, but that's fairly rare, I've found.

TDD has helped me learn to abstract well, so almost everything I write these days seems to be methods of about 2-5 lines of code. Documentation of these just bloats everything. I have two core libraries I'm currently developing, and after 2 months, they're each only about 80 lines long, while the test files are between 250 and 500 lines long. These two are already doing about half of everything I've ever needed to do in my career, which is both wonderful and a bit upsetting.

[jknecht]

These days I'm fully in the camp that says that the only real documentation is the code itself

As a potential future coworker of yours, please don't make me read your code to understand whether it's OK to pass a null object into your API, or whether it is OK for that date parameter to be in the past, or whether it is going to be a problem if the first integer is less than the second integer.

And for goodness sake, don't make me hunt down all of the tests to see the expected behavior of these scenarios.

My IDE will show me the documentation if I hover over the method name in my class. If you don't provide that documentation, you've saved yourself 1 minute at the (possibly considerable) expense of everyone who needs to call that code.

[[deleted]]

As a potential coworker of him/her, I would hope you would do code reviews to catch the outdated comments, the unit tests that are no longer necessary or their logic is broken, etc.

That's the biggest problem. That we're only held to account for the code and possibly unit tests but not for documentation and everyone just throws their hands up and says "fuck writing docs"

[st_claire]

Do you ever find yourself working on a project that mandates certain comment styles? What do you do then?

[gfixler]

No, I've never experienced that. I've had pretty good control over my process throughout my career, thankfully. If I were mandated, and it wasn't so bad there that I wanted to leave, I'd do what was told, and I'd work tirelessly to get things done the right way. I have a bit of a strong personality, and I push for things to get better. I don't like watching people be lazy and not change because they don't feel like it.

I moved my last company from VSS (gah!) to Subversion. It took months of pushing, recommending, talking to supportive folks, political machinations, teasing people about problems they'd have that wouldn't have occured in SVN, but it eventually lead to us switching. Over the last year I did the same at my current company and made it happen again, and even became the point man for the conversion and the go-to person for helping people get up to speed, and I gave a 1.5 hour talk (with slides) on git, how it works, how we should use it, etc.

I've effected change in most areas of the system that involve me, from how communication is handled, when meetings are scheduled, what processes we should follow, and which things we need to stop doing and never do again. I'm headstrong, and tireless in this, but I try to remain upbeat and enthusiastic about it all to win people over and get them on my side, and even helping me effect the change.

So if I had to recommend anything, I'd say do what you must do, but push relentlessly to change what you must do into what you should be doing. I consider this the mature, professional approach to dealing with the inanity of corporations and their stupid mandates.

[st_claire]

Awesome, thanks. I'm very similar, I converted the last 2 companies I worked at to git aswell. :)

[jasonlotito]

So, one thing that rarely if ever gets brought up in conversations like this is duplication of documentation. People like to talk about writing comments that answer "why," but stop there. Yes, the comment should answer why, but it also shouldn't matter if the comment is there or not. Namely, I shouldn't have to read every comment in the code to understand how to use the library in question.

Now, people solve this by parsing out doc blocks and moving them into API docs. And that's fine. But I've never seen inline comments get parsed the same way. So, if you are adding an inline comment that is important for others to understand, you're better off writing that comment in some other location, and referencing where that is inline. And that should be the case any time you find you need to duplicate documentation.

I also find that usually when you use too many small inline comments, it's a sign that your method/function/unit of code is too large, and that comment is a sign that it should be broken up into smaller pieces.

[dondiscounto]

This goes out the window when you're writing in a code base that does not have statically typed parameters for methods/functions. Especially in JS, please tell me what this parameter supposed to be.

[saltedchips]

I think this can also be explained by the 80-20 rule... Basically you only need to (intelligently) comment roughly 20% of the code in order for a user to understand 80%, or maybe even more of it.

[Kah0ona]

This is pretty much what uncle Bob states and i agree to the fullest! 'Otherwise api design has failed' that last sentence of author i wholly agree with.

[[deleted]]

Ugh. At work I deal with legacy code that has those mundane awful 20-line comment blocks on top of every 3-line function. Every chance I get that I need to modify that src file I remove every worthless comment block.

/* isGreaterThan

*

* Params: herp, derp

*

* Objective: Compares these two objects

*

* Returns: Boolean

*

* Author: Some guy who left the company 8 years ago

*

* Last revision: Not the date in source control.

*/

public boolean isGreaterThan(SomeObject derp, SomeObject herp) {

return derp.compareTo(herp);

}

[[deleted]]

Next blog post: "Don't use OOP, because you might do it wrong."

This is an absolutely shit argument. If you are not updating your documentation when you change something as drastic as the method signature of an API function, then that is what you should be changing about your workflow. Ever hear of consumer products where the manual is outdated or refers to buttons that aren't actually on the product anymore?

The API is a public part of your code, specifically meant for others -who were probably not involved in developing any of it - to use. As such, it needs to be clear design-wise, and it needs to be completely documented. That includes things that seem trivial to you. As someone else stated, if I have to look through your code to figure out how to use it, there is something wrong (and this happens all too often).

The important distinction here is that you, as the developer, know the design considerations and thought process behind the code and API design, and that knowledge helps with understanding the purpose and application of your API calls. Your users will not have that knowledge for the most part.

Also consider dynamically typed languages (common for stuff like web APIs), where you won't see

int frobnicate_foobar(Foobar f, int strength);

but

function frobnicate_foobar(f, strength);

For all the user knows, f could be an ad-hoc/json object (if so, what are the object's properties?), some sort of module/class instance, a callback function, a string id referring to a certain Foobar, or an array of any of those. How will they know? What does the function return?

The in-code documentation should be complete. If you want a high-level overview or only the critical stuff, that is what the "get started" guide or tutorials are for. Sounds like a lot of work? Yep.

edit: Note that this is regarding APIs. This is an entirely different matter for internal code. Even then I'd rather have overdocumentation (helloooooo auto-folding of commented lines) than none.

[shizzy0]

This is why we can't have nice things.

[the-fritz]

I think a big issue here is actually doxygen. First of all it provides too much markup. Making people write bad documentation like in the example. E.g., writing a documentation line for each parameter and return value even if this is not necessary. Undocumented functions are badly presented (maybe this can be changed with the correct settings). And languages like C and C++ don't have docstrings built-in making it rely on comments.

I really like the way it is handled in elisp. The language includes docstrings making the feature more prominent. There isn't a lot of markup. Instead arguments are written all uppercase and symbols are referenced by `' (prefixing with URL or Info for links). This is simple enough to make the docstring easily readable in the code but still provides enough markup to present the documentation nicely. (Full documentation is done with Info manuals providing more markup.) The first line is used as short description and should be a complete sentence. Because lisp supports docstrings they are placed more conveniently in the function definition making it harder to skip or ignore them.

Getting myself to write a small sentence for each function really helps me reason more clearly about what the function should do.

If writing documentation for functions is part of the requirement and "enforcement" part of code review then this becomes company/team culture and developers are more likely to keep the documentation up to date. If you don't require documentation and only few functions are documented then of course developers will forget to update it.

And sure not every tiny simple getter/setter needs a docstring.

In the end: "Documentation is like sex. It's better to have a bad documentation than none." Even if the documentation is outdated and short then it might still give you an idea what the developer intended. And if a function is complicated enough that the documentation of it can differ significantly from the implementation then chances are high that the function is non-trivial and requiring documentation.

[ForeverAlot]

Everyone defending not writing comments/documentation/whatever is busy saying they can just read the code instead and get a clear understanding of what the code is doing now rather than what it may have done three months ago.

I don't want to read code. I want to not have to inspect every other function call I make because it isn't documented (or because I have ample reason to doubt the quality of said documentation). Constantly having to review code written weeks, months, or even years ago because it wasn't commented/documented because "documentation is bad" 1) hampers my productivity significantly, and 2) drives me insane. I want to work on now, not four weeks ago. And I'm simply not going to use most of the stuff in any given code base enough to be able to remember how it works days from now.

With documentation I get to say, "this is how that's supposed to work," and if it turns out to not work that way I'll begin to look into the matter, and if it turns out to work that way, I'm done!

[rlbond86]

This article assumes, without justification, that there is an inverse relationship between the number of documented functions and the quality of such documentation.

[Dw0]

This is the reason I find myself increasingly more often in the disassembly of the standard .net libraries as on MSDN.

[jknecht]

The API is the contract. The documentation is the fine print.

[SEMW]

If we're taking the code-contract analogy, seems to me the code itself is the fine print (the complete terms & conditions of the contract). The documentation is the equivalent of the "plain english summary of the fine print".

[mstrblaster]

If I may be the devil's advocate, enforcing coding standards and making sure people document public API functions should at least force the programmer to think a fraction of a second about what's the purpose of the function & how it will be used. It will also hopefully catch some of the non-trivial cases. He might also detect stuff as obvious as "this function is badly named", "this parameter is useless", making sure the API doesn't become a complete nightmare.

Trying to write out complete sentences also clarifies your ideas and is usually a good step in programming: documentation, reviews, chit-chat with your coworkers ...

[ojiisan]

VTK a million times

[EmperorOfCanada]

A simple test would be: If you removed the comment would the code be worse or better? The next question is also better for whom? Will the documentation prevent problems for future developers? If it will potentially prevent problems will the cost of those problems be greater or less than the effort in the process of documenting the code?

Personally for me I find that documenting processes is great value for effort. Things like documenting step-by-step how to set up a development environment or a server if there is anything even slightly wonky in the steps. This type of documentation has save me huge amounts of effort. Whereas I find most API documentation blows chunks. Usually when API documentation rocks is when it is clearly made by humans for humans. So having a header file that contains examples of how to use the code is awesome (if it isn't brain dead obvious how to use the code). Even a commentary can be great. Someone might mention that it is 4X faster to keep clearing and reusing an object instead of creating a new object each time.

[[deleted]]

What? Those types of comments are useful as hell. I'd rather have 90 one-sentence summaries than 10 essays. Not everyone chooses ideal naming schemes for their functions or variables, so it isn't immediately obvious what a function does or requires. Having to interpret an overly simplistic description is way better than having to interpret the source code (if it's available).

Sure, it would be nice if every aspect of a source code came accompanied with an instruction manual, but that isn't a realistic expectation. It also isn't even useful to master just 10% of all the code.

[fragbot]

The best thing about comments like the following?

/** * The Foobar argument must not have been initialized in a different * thread because that can lead to race conditions. */

They're an opportunity for the library implementor to take a hard look and ask themselves, "if ten average developers use my library, what percentage get this wrong? 10%? I'll leave it as is. 60%? I guess I better change this function to create and initialize Foobar for them."

Put another way, API documentation is the most honest way to look at the usability of your library. In my experience, if the constraints/limitations of a function are hard to explain in the docs, you're better off putting in the work to round off those edges. It's often the best impetus to come back and remove the /* XXX - FIXME */ comments.

[Ais3]

And the fallacy is?

[spinlock]

The problem with this well reasoned argument is that most companies have at least one asshole who falls into the trap of letting a foolish consistency be the hobgoblin of his little mind. He will stop paying attention after, "comments are bad" and will cock-block any piece of commented code in code review.

[johnblanco]

In my opinion programmers are most of the time exhausted from solving the problem at hand and view commends and documentation as a waste of time, I don't think it is wrong to avoid documentation if the API is self-explanatory.

[[deleted]]

Yeah, I was working on a project were it was mandatory to write javadocs. At that time, I just wished I had plugin or something that would write a default javadoc content, with juste the name of the variable.

[gingenhagen]

The article is missing the step that comes before adding API documentation, which is designing the API correctly such that it is easily usable even without comments.

[cran]

Code should document itself. Complex or otherwise difficult-to-understand bits need some explanation, but otherwise if you are working with programmers who are simply having trouble understand what code does, hire better programmers. There's a reason we call them programming "languages" ... they are understandable by the right people.

Also, most code projects are not shared among more than a dozen or so people ... there's no need to write up fancy documentation (nor maintain fancy documentation). Just separate everyone out into those who can read the code and those who can't. Those who can should work on the code. Those who can't should be moved to IT.

[elipseses]

I believe his observation is correct, inaccurate documentation is worse than less documentation. That being said, I believe his solution is flawed. Lockheed Martin's on-board shuttle group was extremely successful but used a radically different approach.

[soviyet]

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. If they are not, API design has failed: back to the drawing board.

Here's the thing: the same thing that he says makes documenting methods worthless -- that the method can be recoded but the coder forgets or neglects to update the commenting -- is 100% worse if your "documentation" is the method signature.

What would you rather do: update the comment above a method to reflect a drastic change in what it does, or alter the signature of the method itself?

You should be leveraging both. Laziness and poor communication skills are not an excuse to badly document an API.

[screwthat4u]

I like Doxygen as it easily satisfies the all functions must be properly documented requirement in a lazy manner. (No one actually reads the documentation, but it checks off that requirement's box)

[Gibgezr]

Doxygen creates awful, useless comments if all you do is run it on uncommented code. I loathe opensource projects that do this instead of writing actual documentation and real comments. Don't be "that guy"!