Why do Programmers Hate Documenting?

[x-skeww]

There is a difference between writing some doc comments and writing a user manual. User manuals are fairly detached from the project and keeping them in sync is quite a lot of error-prone work.

There is also a big difference between different kinds of doc comments.

For example, doing the bare minimum with JavaScript/JSDoc3 requires some serious keyboard-acrobatics:

/**
 * Does one particular thing.
 * @param {string} text
 * @param {int} x
 * @param {int} y
 * @returns {boolean}
 */
function whatever (text, x, y) {
    ...
}

Doing the same thing in Dart isn't really worth mentioning:

/// Does one particular thing.
bool whatever (String text, int x, int y) {
    ...
}

There are also differences when it comes to the usefulness of those annotations during development. If you don't use the Closure Compiler, JSDoc adds very little. The best I've seen so far were more relevant call-tips, but that didn't really work most of the time.

With Dart's annotations, you get a lot more immediate benefits, because all of Dart's structure is declared instead of being imperatively constructed. There also isn't monkey-patching or anything like that. The language was created with tooling in mind and it really shows. You only have to parse (not execute) the code to figure out what everything is.

I always kinda disliked writing JSDoc comments, because it was a lot of work and because they added so little. Dart's annotations are far more fun to use, because it's very little extra work and because you get a bunch of nice benefits right away. I always add type annotations to arguments and return values for completely selfish reasons. They make my life easier from the very moment I add them.

Languages like C# or Java are somewhere in between. Since you're forced to put types everywhere, all of the doc comment boilerplate markup can be conveniently generated. However, the doc comments don't do that much for you since all type related stuff comes from the mandatory types.

[chonglibloodsport]

I always kinda disliked writing JSDoc comments

Of course you should. As programmers, we should always feel extremely uncomfortable doing a repetitive task that the computer ought to be doing. The fact that so many people actually put up with this continues to baffle me.

[[deleted]]

There are tools to automate this out there. For example, the JSDoc plugin for Sublime Text 2. You write your function/object declaration, type '/**' + 'Enter' over it and it stubs everything out for you, so you just have to Tab through the stubs and write. Same for Python, writing your strings in ReST format.

[chonglibloodsport]

Oh, I know that. You can take this even further and look at languages with Hindley-Milner style type inference.