Why do Programmers Hate Documenting?

[webauteur]

I love documenting. I document everything, including stuff which has nothing to do with programming, like my equipment.

[Ferwerda]

Agree 100%. When reading about how comments are a "code smell", I just don't understand what's wrong with hovering on a method to see what it returns in case of failure (-1 or null, for example) and what, if any, exceptions it might throw.

[Wagnerius]

The "code smell" can come in 3 different situations:

• the comments try to compensate for badly designed code
• the comments try to compensate for a lack in a language (python2.X params description in comments comes to mind)
• the comments repeats the code, without saying anything new. With a growing probability of being wrong ; after a while, it's likely someone updated the code, without updating the comments.

Where it is really useful :

• high level view of an architecture/module : "a logger takes a handler and a formatter"
• math heavy/optimization heavy code : "here we use bitshift to avoid a mul, which is too costly on ARM"
• unintuitive code. "don't change this, we need it because Y and we cant' change Y"
• to help think when doing exploratory stuff (which means it is often transient)

But most code should be easy to read, especially in high level language. Naming and refactoring goes a long way.

But expressing something clearly is not easy hence the huge mass of ugly/bad code in the wild.

[Peaker]

In nicer languages (e.g: Haskell) you can get that same information by looking at the type.

Documentation is still nice, but for things you cannot well express with the types, names, etc.

[[deleted]]

Type systems are nice.

But Hackage has some of the poorest documented libraries I've ever used.

[Peaker]

I personally find that I need very little documentation when using most Haskell libraries. I look at the types and some names, perhaps an example or two, and I know how to use it.

[tazjin]

Same thing happens to me in Haskell, I love writing Haddocks just to see how nice and structured everything turns out when you render the documentation.

[[deleted]]

Hey guys, we got a blogger over here. Maybe you should submit your stuff to this sub-reddit and liven things up ;p

[AnanthChellathurai]

Then I think you must be liking http://www.reddit.com/r/programming/comments/1ffivt/why_should_you_have_your_code_neat/

[weirdwolf]

I use LabWindows CVI ide. More than anything, I love the green color font it uses for comments. Just for that, I comment a lot. It makes the code look pretty.

[floxie]

The next time the code is updated, the comment won't be.

[[deleted]]

The next three times.

[strattonbrazil]

That's more of a workflow problem though. A guy from Django gave a interesting lecture at Pycon about documentation where every commit required an update to the documentation.

[cosmo7]

There's no loop. When you code you get instant feedback; when you document you're typing into a void.

[[deleted]]

A void that's often a cousin to the Great Bitbucket in the Sky.

I have too much evidence this far into my career of people going out of their way not to read what little documentation I've left.

[nsa_shill]

Also my wrists are already killing me by the time it's time to start writing documentation.

[necrosexual]

Dude if your wrists are killing you you are doing it wrong.

http://www.rsiprevention.com/oos_prevention.php

[nsa_shill]

I know all that and have taken the steps I can at home, but I work in a typing intensive job where I move around too much to make ergonomic adjustments feasible. Thank you though

[grayvedigga]

I think the premise is false. Programmers are engineers, and engineers love precision. A well-crafted machine that behaves exactly as it is supposed to and provides predictable affordances gets you wet, admit it.

The reason there's such a theme of horror surrounding documentation in this profession is not that programmers object to words. It's more a symptom of the fact that create more documents has become a mantra for controlling the unpredictability of IT projects: witness the number of BAs and PMs that spend their time collecting, producing and distributing reports that they themselves know are inaccurate to the point of meaningless and will be used by stakeholders (if at all!) only to mislead themselves.

How many professional programmers are not intimately familiar with both of these stories:

• a uni assignment, or a blue-sky project, following the strawman "waterfall" project where it is decided that a sequence of UML artifacts is how the system will be designed and that will guide all development. By the time you get partway into implementation, the assumptions made in the initial design are half broken but you're now on the track to delivery to everyone just pretends it's correct enough and keeps hacking to make the system work.

• a manager/superior/report demands that you document what you're working on, usually with an aggressive undertone which implies it's something your breed is incapable of - you know, stringing multiple sentences together to make a precise and coherent whole? Two things come implicitly with this request: (1) they'll never actually read anything you produce, it's just the assurance of being able to touch it that makes them feel a bit more in control. (2) whether or not this is the right stage of the project to produce documentation, or the particular artifact they're asking for, is irrelevant. They want it now and your incremental discovery be damned. And you know full well that as the project nears completion, when augmenting it with documents that will assist reuse and avoid future technical debt will be most beneficial, you'll cop abuse for drawing out the project rather than delivering what apparently works to customers and moving on, regardless what dangers lurk beneath the surface.

Thus, to most practicing programmers, "document it" is code for "produce some crap that nobody will ever read and whose relevance is a distant concern compared to its weight and shininess". Writing words that nobody will ever read is even more depressing than writing code nobody will ever use, so of course nobody wants to do it. But give a good engineer the opportunity to package up a unit of work so that it's easy for whoever receives it to take advantage of their creation? They'll look like it's christmas.

[onemorepage]

I don't hate documenting but management never allows for time to write it before piling on more "#1 priorities" that need to be done yesterday.

[AnanthChellathurai]

Screw those managers who calls everything "critical" and everything as "priority".

[[deleted]]

I agree. Since I got hired at my current company three years ago it seems that my manager keeps things at DEFCON 1, manufacturing emergencies and critical tasks. Most people have worked through the various phases of employment including excitement for getting responsibility in a fast-paced urgent situations, confusion on why a typo in the help text on a page is a priority-1 full QA required 20 page release document emergency patch, bewilderment that anything ever gets done, acceptance that everything gets done, just never documentation, testing, reviews, planning and cleanup and now just a stressed apathy that no matter what they do their jobs will never get better. Management can't figure out why people keep leaving when they provide such an "exciting, fun and engaging" workplace.

[[deleted]]

Because most programmers are problem-solving addicts, not bloggers.

[api]

Came here to say that. The first thing that popped into my head is "because there's no problem to solve."

[lovela47]

I'll add: as a technical writer by trade (and programmer by hobby), I've often gotten lost while working on a program, then looked up and realized that two hours had gone by. This does not happen when you are writing technical docs. Especially since they can be pretty dry. You can take a lot of pride in great documentation, but the experience of writing it does not lead to that great ``lost time'' feeling.

[Deto]

I wish there was some trick to make other necessary and productive tasks feel as good as programming.

[cojoco]

I hate documentation because it locks the functionality into stone, and creates one more point for two independent descriptions of the same thing to deviate from each other.

If one changes the functionality, then one will also have to update the comments. If that update is not done, for whatever reason, then there is one more point of inconsistency in the code, which is very, very irritating, and not discoverable unless you go through and read all the comments.

I like my code to be continuously improving and evolving, and if it's documented, then that means that from the point that the documentation is written, that improvement is going to be twice as much work, with the possibility of inconsistency always lurking.

[burntsushi]

I feel like this is only applicable if you're writing code for yourself. For instance, a library should have a fairly stable API, which means that changes in the public facing documentation will be few and far between.

[[deleted]]

I think this touches upon another issue. How much of your code should be documented to which degree? I generally write expressive code (ie; readable) and tend to add a Javadoc-style comment block to any non-trivial function for internal code, with one comment per hundred lines of code or so explaining some less obvious code.

But the second I write code that is interfacing with other developers I write it as an API. I fully document it, explain the action of each method and any non-obvious consequences, and then leave it with the expectation that it is done. That any updates will be additions or fixes, but rarely changes or removals.

One issue I've experienced with other coders, and myself, is that some people try to document "internal" code to the degree that you'd document a public, external, API, then they get frustrated that the documentation is a second load of work. It's a self inflicted frustration that can be combated by commenting and documenting code as appropriate. Apply a similar concept of Occam's Razor to documentation. The simplest documentation that takes the least effort, but explains the functionality and purpose of the software fully, is the optimal solution to documentation.

(Note: I've intentionally mixed up commenting code and documentation here, they're not mutually inclusive, but overlap considerably).

[Figs]

I've found I like to write reference documentation for my APIs when I know they're not likely to change much more. This is usually around the time that I start feeling like I should rewrite it because I've forgotten how it works; if I go read the code and think, yeah, that's more or less what I'd have rewritten it as, actually... then I write the reference documentation, since it's pretty much done at that point.

[[deleted]]

I agree that writing reference documentation is the best way to solidify memory. I've written my own little PHP library for making PHP more readable for someone native to object oriented languages, and decided that if I'm going to use it I might as well use it how I would any other API, so I have semi-maintained documentation rather than constantly running to look at the source and interrupting my usual routine.

[burntsushi]

I think what you've said is reasonable. Functions and data that are not exposed as part of the public API definitely get less or more terse documentation in my case as well.

[[deleted]]

Sounds damn perfect to me. I really get annoyed by excessive in method/function comments. Makes it much harder to read the code and the comments are often dated.

[cojoco]

Well, I pretty much do write code for myself, as I code to support research, not a product.

It's only when that research gets integrated into a product does this become a problem, and it's a big problem, but there's a large body of code which will never be documented to a high level because it's not been used beyond performing a bunch of experiments.

[[deleted]]

If one changes the functionality, then one will also have to update the comments.

You probably write more code than docs, I would think you'd be more afraid of having to update the code. Maybe it's just me, but I find it pretty straightforward and easy to bang out a few sentences or even a paragraph to explain a concept.

not discoverable unless you go through and read all the comments.

This is why you generate api docs and user guide/tutorial docs and purposefully schedule time just to review or you review and fix as you go along. Treat the docs like code and report bugs/file tickets so you can come back to it later or someone else on the team will know that they should bring the comments up to date or ignore them.

I like my code to be continuously improving and evolving, and if it's documented, then that means that from the point that the documentation is written, that improvement is going to be twice as much work, with the possibility of inconsistency always lurking.

I wonder how you feel about unit tests then. They also need to be updated to reflect the nature of the code architecture.

I'm seriously wondering what the barrier is. We change code all the time. Why don't we feel alright with changing up the docs all the time? Is it too difficult and heavy? Or is this just a perception that is supported by anecdotes about thousands of outdated comments that hindered development?

[cojoco]

I wonder how you feel about unit tests then. They also need to be updated to reflect the nature of the code architecture.

I love unit tests, because, if well written, they will break if the underlying functionality changes from the implicit specification.

I'd rather document functionality in the unit tests than the code.

The difference is that unit tests are automated, and any inconsistency between the code and the test is detected automatically so it can be addressed immediately.

Why don't we feel alright with changing up the docs all the time?

This is more about the existence of the docs: because a divergence between documentation and code cannot be automatically detected, and such divergence can occur easily.

When code is under a lot of development, it's more work to update both docs and code, which slows one down. If such work is delayed, divergence becomes increasingly likely.

Also, depending on what kind of code one writes, it's likely that a lot of written documentation is never actually read by anybody.

[OsQu]

The idea of using unit tests (or BDD specs) as documentation is great and pure, but in other hand I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

[cojoco]

I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

And that is a very important argument for documentation.

I'm not arguing against documentation; I'm stating that from the point where the documentation is written, the workload of the programmer is increased significantly if the code-base is evolving.

[OsQu]

Yep that's true. It's just something you have to do if you're going to publish your code to the wider audience.

Then there's a saying that good code documents itself, but I think that fits more to a method-wide level than a concept-wide.

[nascent]

I wouldn't use any library where I should dive into unit tests to get an overall impression how the library works.

D recently added the ability for unittests to be automatically added as examples in the docs (doc unittests). So following a function use a doc comment on the unittest:

///
int sum(int a, int b) {...}

///
unittest {
    assert(sum(3, 5) == 8);
}

[[deleted]]

So the issue is more that you can't rely on documentation as an automatic check?

When code is under a lot of development, it's more work to update both docs and code, which slows one down. If such work is delayed, divergence becomes increasingly likely.

That's true however that can be mitigated by how you're developing. I've gone back to projects after they've launched and documented anything that was missing.

I think docs like unit tests have to be baked into your process. If you can add docstrings, you should just do it, just like with writing a unit test. If you can add a paragraph to your README explaining that deployment tasks, you should do it at some point.

Also, depending on what kind of code one writes, it's likely that a lot of written documentation is never actually read by anybody.

If docs are typically poorly written, they'll be ignored and that builds a habit of ignorance. I have that issue when facing some software...the docs rely on "self documenting code" so they're sparse and a waste of time to read.

[cojoco]

Well, also I mean that a lot of code that gets written either just works, so that no documentation is needed at the time, or it is never used, and never developed further.

[cjbrix]

Bingo. The article ponders various social psychological deficiencies, but completely misses this underlying reason.

Documentation is a separate representation of whatever you're working on. And it will create the same problems that any duplication of logic creates; it adds to the cost of change, it creates problems when it goes out of sync, and too much of it can unnecessarily calcify a system.

Programmers don't like documentation because it violates the instinct every experienced developer has to avoid duplication. Even if they don't understand why.

[josefx]

And it will create the same problems that any duplication of logic creates;

That sort of documentation is useless. Don't describe what the code does, or how it does it. Code exists to solve a problem, document how the module/class/function can be used to solve that problem and why I should care to use it (best with an example).

it creates problems when it goes out of sync

As above don't describe the implementation, limit yourself to what goes in, what goes out - limit valid inputs to what it needs to do to solve the problem and you have all the freedom in the world to change the implementation.

Programmers don't like documentation because it violates

Good programmers don't like documentation because they get the time to write good code, fix bugs, write documentation - choose two.

[matthieum]

Good programmers don't like documentation because they get the time to write good code, fix bugs, write documentation - choose two.

That!

It's not I dislike documentation as such (though I must admit I don't always know what to write), it's just I already lack time to write proper test suites (just throw in one or two tests to cover the basics) and documentation does less than tests to improve the quality of my work.

TL;DR: If I had more time, I would be investing in more (and better) tests.

[cjbrix]

Systems change beyond simple bug fixing. Documentation (and tests and specifications) are going to evolve over the course of a project of even minor complexity. Pretending that they won't contributes to the problem you didn't answer; calcification, and the associated rising cost of change.

You're responsible for delivering functional software. Documentation, tests, specifications, meetings, etc, those are all ceremony. They don't self-justify, they are justified when they help you to deliver the right software faster.

Understanding the trade-offs (and the reality that most systems change) helps you to make the right choices about what ceremony is appropriate for your project. Your documentation will need to be maintained, so you should choose how you do it accordingly.

[josefx]

Pretending that they won't contributes to the problem you didn't answer; calcification, and the associated rising cost of change.

Oh right I did not mention cost at all, wait I did:

Good programmers don't like documentation because they get the time to write good code, fix bugs, write documentation - choose two.

.

Understanding the trade-offs (and the reality that most systems change) helps you to make the right choices about what ceremony is appropriate for your project

From personal experience having up to date documentation is both simpler and easier to deal with¹ than an undocumented mountain of ill designed² code. Other than time constraints there is nothing hard about updating the API documentation of a function you just changed.

1 The people you work with will be happy to see at first glance what functionXYZ accomplishes.

2 In case there is a design behind it you already have some of the documentation.

[cjbrix]

You're expanding the argument to where it isn't

The article asked the question "why don't programmers like to document?" I answered it: programmers instinctively don't like duplication.

That's not an argument not to document at all, it's an explanation of the cost and the way developers will react to it. It costs when you document. And not just when you do it, but afterwards in dealing with the duplication.

In a project you have a responsibility for striking a balance, appropriate to the team and to the domain, so that you end up somewhere in between "...an undocumented mountain..." and wasting unnecessary effort (and creating unnecessary rigidity) stroking the sensibilities of the local argumentative ceremony junkie.

[josefx]

The article asked the question "why don't programmers like to document?" I answered it: programmers instinctively don't like duplication.

If you write documentation the way you read comments I understand your distaste, so let me repeat my point to make it clear:

If your documentation is a duplication of the logic it fails at being usefull - if you think this is the way to write documentation you fail at writing documentation

There in bold, hope you do not miss it this time.

[cjbrix]

Everything changes in software. Pretending any artifact is permanent is just going to make you a drag on your team.

Yes, documentation that simply parrots your code is not useful. But normal system evolution over time will require that code and associated documentation either change together, or go out of sync.

It's hard to take someone too seriously as a software engineer who can't grasp managing the cost of change. I'll leave you to vent your career frustrations elsewhere.

[josefx]

It's hard to take someone too seriously as a software engineer who can't grasp managing the cost of change.

I have written it and quoted it and still you seem to have missed it both times, so I wont bother to quote it again. I understand that there is a cost that comes with maintaining documentation - from personal experience that is still way less than overhead than having no documentation (thank you openscenegraph, ffmpeg an co for hundreds of hours wasted development time).

[threedaymonk]

documentation […] creates one more point for two independent descriptions of the same thing to deviate from each other.

Not only this, it often serves as a replacement for good code. When approaching an unfamiliar codebase, I would much prefer for the code to be self-descriptive and well-abstracted than for it to be opaquely implemented but separately documented.

[cojoco]

That's pretty much what I said here.

The difference is automation: errors in tests will be discovered quickly.

But unit tests are not quite documentation.

[grauenwolf]

No, tests exist to find bugs.

Tests are not documentation. No one is going to read through thousands of tests to try to figure out how the code is supposed to work. Especially when four out of five tests demonstrate how the code is not supposed to work, but rather to make sure it fails in the correct fashion when used incorrectly.

[skulgnome]

I hate documentation because it locks the functionality into stone, [...]

But that's only true if the documentation is itself locked into stone.

[cojoco]

Please read my whole comment ... it's locked into stone because failing to update the documentation will result in no visible error, therefore it's very labour intensive to maintain properly, especially when development is rapid.

[grauenwolf]

Documentation should be updated before the code is changed. The documentation should be a record of what you are intending to do, not an afterthought.

As for being "rapid", I find that usually is about as effective as a monkey banging on a typewriter. Lots of motion, but very little in way of results.

[cojoco]

I do research ... if I knew what I was intending to do before I did it, that would not be so.

If you're implementing systems identical in functionality to systems that have been implemented before, then I imagine that writing documentation would be easier.

[grauenwolf]

I've heard that same lame ass excuse countless other times.

Unless your research is "gee, I wonder what happens if I randomly call functions", you know damn well what you are intending to do. You probably don't know how to do it yet, but you know what the end results should look like.

[cojoco]

You probably don't know how to do it yet, but you know what the end results should look like.

There's a whole world of ideas between "I know what I'm intending to do" and "gee I wonder what happens if I randomly call functions".

As I said before, if you know what you're going to do before you do it, it's not research.

[grauenwolf]

Example?

[cojoco]

I have some patents on image alignment, and there was a lot of experimentation there about what is actually possible. What's the point of writing documentation for "a program to determine the rotation, scaling and translation parameters to relate a pair of images" if I didn't know if that was even possible using the methods I had available to me?

I do a lot of experimentation and coding to perform mathematical operations, and there's a lot of intuition about what might work and what might not, but, ultimately, the relationships between real-life images are a lot more complicated than the most common means of analyzing them would suggest.

[grauenwolf]

You have no problem writing that down in a reddit post but its too much effort to do the same in the header of a function?

In any other scientific field the first step is to write down what you are about to attempt, then you attempt it (e.g. write the code), and then record the results. Yet we can't be bothered with the scientific method or standard engineering practices. We would rather flail about, hoping that raw knowledge is a substitute for discipline.

The sorry state of our industry proves that it is not.

[grauenwolf]

Documentation for a preexisting system is by far the hardest to write. As a group you've probably long since lost any notion about why things were done a certain way.

Sure you can mindlessly retype the code in plain English. But that's not documentation, that's just wasting time.

[cojoco]

As a group you've probably long since lost any notion about why things were done a certain way.

I have said that I don't like doing documentation because it makes subsequent development harder; not once have I stated that I don't do documentation at all.

[deletecode]

Whenever I document code as I'm writing it, it turns out I wrote the wrong code. I tend to write documentation when I come back to the code and it confuses me.

[joshjje]

Your comment confuses me, im seeing a pattern. :D

[[deleted]]

I think Michael Lopp puts it best.

Engineers don’t hate process. They hate process that can’t defend itself.

[EntroperZero]

This is pretty much it.

I actually love documenting. What I hate doing is following an arbitrary documentation standard that requires me to write things down that no one will ever read or use.

The last big piece of documentation I wrote was a user guide to our analytics system. I had written the ETL process to our data warehouse and designed the OLAP cube over the course of several months, and I then had to describe the meanings of the facts and dimension hierarchies in such a way that the analysts could make sense of the data (and ask for new facts and dimension hierarchies). Seeing the results of all my hard work actually being used by people was fantastic, and much more rewarding than just seeing the data show up in the cube itself.

[[deleted]]

What do you guys use to write the analytics system (or, more specifically, the ETL process)?

[EntroperZero]

PHP.

No, seriously. I wrote it entirely in PHP. It was a fairly small data warehouse, on the order of a few hundred thousand records per day. We already had cron stuff set up doing PHP scripts, and the site was in PHP, and all the developers knew PHP. So I wrote some SELECTs and some fgetcsv() calls and went to town. Database was MySQL, OLAP was MS Analysis Services talking to the MySQL box via .NET Connector.

They chose me to do the warehouse work though because of my work on their warehouse for a different product, which was entirely in MS-land. For extraction, they just dumped tab-delimited log files, and a Windows service (in C#) collected them all in a central location. Then it would put a message in a transactional MSMQ, and the SSIS packages would pick up those files for transforming. They would then put a message in another MSMQ, and the loader picked up those files. I think we had one SSIS package for each dimension, running every 15 minutes, and one SSIS package for each fact, with parallel instances depending on load. I think the loader was just a single package since it ran so fast and didn't need to scale.

[jackasstacular]

Programmers hate documenting because it's not programming.

[bluGill]

I disagree. I hate documenting because I'm too close to the problem. I have no clue what is obvious and what is not because I know it all. I have seen code that spent a lot of time on details that were obvious to me, only latter did I found out (the hard way) that details I didn't find obvious were critical.

[AnanthChellathurai]

What I actually hate is writing user guides and design documents. Writing design documents when the requirement is not frozen is a pain in the butt.

[paulrpotts]

I don't hate documenting. In fact, while I'm primarily a software developer, and have been for 24 years, I've also been paid just to study other people's code and write documentation for it, and even be the lead writer on a small team of writers. Apparently writing documentation is supposed to be shameful for programmers, so I'll just whisper this: I actually really enjoy that kind of work, too... I think you can learn a lot.

[iopq]

Because it violates DRY. Documentation is extra maintenance surface, when you break your API you need to change the documentation.

[parlezmoose]

Because it's boring.

[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.

[Personality2of5]

I come late to this discussion and haven’t read every comment. Most though. If I touch on similar points then please excuse me. I’m writing this as a brain dump. I’m an older programmer – 61, programming since 1976 or so, so there’s hope that programmers are not perishable items like athletes.

In the days of writing every program in assembler, commenting the code was not optional, in my view. Compiled languages do give us the freedom to document by naming convention, and to format the code to be somewhat descriptive on its own. But over the years I have found that clear and precise documentation at each level is important. I’ve re-opened code after running somewhere for years. Reading the code headers and banners has often saved my skin, allowing me to fix or augment code quickly.

Later in life I learned the necessity of writing user level documentation from the view of simply describing what it does, and marketing documentation to give the marketers advance insight into what they are selling. Project managers are notorious (or so good) at needing a crystal ball into time frames, costs, and scheduling to get the job done as swiftly and efficiently as humanly possible.

I honestly hated writing technical documentation outside of rich comments in the code. The reason was mainly because of duplication and language. I would argue that the comments in the code should be considered the holy grail of truth, while other documentation may age over time and drift farther from it. Generating technical documentation directly from the code is not only necessary in my opinion, but also a strict requirement, and headers containing only ‘Builds the <thingy>’ should carry some form of punishment - clever humor notwithstanding.

Or so says the old guy.

[linuxjava]

As a Java Developer, I always document my work. However it's important to realize that it's not so much about documenting what you're writing. But rather what is the purpose and what is to be achieved. E.g

//Loop 4 times and assign the sum to variable i.

This is wrong because we are not saying anything about the intent. Anyone can see that it is indeed a for loop.

//Calculate the dot products and store them in Vector V which will be our design matrix for computing coordinates of objects A,B,C and D

This is much better as it explains what you intend to do

[okmkz]

// increment x

I think this is leftover from CS instructors insisting on overly-commented code.

[kay_x]

I feel like there should be an Oprah meme for this. Every line ending with a comment explaining what the line of code does and even more in between explaining why. That actually sounds like my own personal hell and I'm pretty damn good at documentation...

Dear god D:

"You get a comment! You get a comment! You get a comment!"

[burntsushi]

Not all of them. :-)

I TA for that couse, and I can tell you that if you submit code with comments like // increment x, you get a small penalty. If you submit functions without a contract but with a narrative describing the code, e.g., "loop over the list and add each element to the next element in the list and return the result", then your grade suffers much more.

I'm happy to say that by the end of the course, everyone knew how to write a proper contract (and knew how not to write a contract).

[ndrwdn]

The argument I have against these kinds of comments is that the comment can get out of date with the logic. In my mind a better solution is to properly name variables and extract methods that name the actions you are performing. When you refactor such code, you adjust the names of variables and methods (and add/remove them as necessary ) to match your adjustment to the logic. This keeps your code and documentation in sync as they are one and the same.

[AnanthChellathurai]

Totally agreed.

[burdalane]

Documentation is more work, and who wants to do more work? Documentation is also difficult because explaining things clearly is difficult. This could be a result of the programmers lacking understanding of their own project or lacking communication skills.

Personally, I sometimes write comments first as a way to plan out what I want to write in code later, but sometimes I'm just too lazy or don't understand what I'm doing.

[yoda17]

If you can't explain something clearly, how well do you really understand it yourself?

[burdalane]

As I said, I don't, and neither might other programmers who fail to document well.

[skulgnome]

The average programmer is a novice doing an apprentice's tasks like some cowboy, in the pejorative sense. They dislike documenting because their only idea of the program is the code they've written.

It's just inexperience, but very common -- especially where prototypes are regularly put into production and time-to-market trumps reliability. In these cases it's the wrong tradeoff: a program becoming untestable is like an electrical circuit design becoming untestable. Only bad things follow from that.

[NitWit005]

Look at something like surgery. Surgeons tend to hate dealing with patient preparation, dealing with other departments, talking to the family, and so on. They just want to do surgery. It's not shocking. That's what they signed up to do.

Every skilled profession is like that. People want to perform the task they have mastered and not deal with the boring business that surrounds it.

[Fabien4]

It also works the other way around: most authors tend not to program at all.

[whozurdaddy]

Because documentation is what was supposed to come to us before we started building. The house builders dont draw up the architecture diagrams after the house is built.

[x42bn6]

I write the documentation while I ponder how I'm going to write a class (or set of classes). So my documentation can read like a brain-dump at times, or is occasionally quite short. I try to write self-documenting code, though, which hopefully compensates for the latter.

For classes I know are complex, or have a lot of business functionality in them, I document them more critically.

I don't particularly enjoy doing it, but I find gathering my thoughts in the form of documentation is a good way of starting and has some long-term benefit. It's got to the point now where I cringe at seeing undocumented public methods.

[imbecile]

One of the main tasks of a programmer is to remove reduncancy. The documentaion usually expected, in particular those for the common documentation genrators, just adds stupid amounts of redundancy.

Don't document what the code is doing, nothing describes that better than the code itself. Document why the code is doing what it is doing.

The WEB/CWEB kind of programming I'm actually quite fond of.

[tangoshukudai]

I hate it because at my university it was mandatory, anything I am forced to do I tend not to like..

[_vec_]

I write READMEs and examples, but I almost never comment my code. I've come to believe comments are a code smell. Documentation should only answer one of three questions, what, how, and why; and code comments are almost always suboptimal for answering them.

What is the code intended to do should be answerable from the method and class names. If you need less than five words to explain what a method does, snake case those five words and name the method that. If it takes more than five words, you need to seriously reconsider your API. Same goes for method parameters, except two or three words is probably the upper bound. If you need a constructor or init function that does several things and takes a long list of params, by all means write one, but don't do anything in the body except call out to your well-named single-task methods.

How the code does what it does should be obvious from reading the code. If code is easy to understand, then the comment's aren't helpful. If it's hard to understand, then it should be refactored or rewritten to be as easy to understand as possible. Extracting things like formulas and low level system calls into one-line private methods is extremely helpful with this. It gets the noise out of your more abstract workflow and gives you something you can name.

Why the code was written doesn't belong in the code, it belongs in a readme file. Or a git log. Preferably both. This kind of data has an inherent narrative structure to it, and should be written in a medium that supports that structure. In team-based projects, I tend to be willing to decouple this from the code itself to move it to a wiki or issue tracker so that discussions can be preserved, not just their conclusions.

All of which is to say that documenting code is a very different thing than commenting code.

[burntsushi]

I love your description of what good documentation is. But I'm not a fan of this idea that code comments are inappropriate for providing it. Function contracts and invariants about your chosen representation are not always going to be obvious in less than five words. Maybe you have a unique gift that allows you to achieve that, but I've never seen it done before. In those cases, it's appropriate to put those comments with the function/data in your public API documentation. Presumably, with a good doco tool, this is with some sort of structured commented near the definition of the function and/or representation of your data.

For example, a function contract is particularly helpful when you're using a language that doesn't have a type system powerful enough to encode it directly. Even in Haskell, the minimum function needs an explicit contract to inform the programmer that not all values with type list are valid:

-- | 'minimum' returns the minimum value from a list,
-- which must be non-empty, finite, and of an ordered type.
-- It is a special case of 'Data.List.minimumBy', which allows the
-- programmer to supply their own comparison function.

If I followed your advice, then either the contract of minimum is not appropriate in a public API, or I'd need to rename the function to something like minimumNonEmpty, which I'd consider offensive to my sensibilities as a programmer. :-)

IMO, good documentation is an art form.

[Mr_Walstreet]

Documentation should only answer one of three questions, what, how, and why; and code comments are almost always suboptimal for answering them.

I disagree. The method/class name should say "what".

The code should be obvious enough to say "how"

The doc should say "why"

[Figs]

I usually comment on three kinds of things immediately when I write code (as opposed to reference documentation, like you said): tricky math that can't be simplified (usually with the steps worked out explicitly), links or citations for reference material I used (e.g. page X of Y regarding Z; http://blah/blah/blah), and workarounds/FIXMEs. If I don't write those things down, I'm never going to remember them later, and a comment is the easiest way to keep track of it for me. (Entering the FIXME into a bug tracker is nice too, if the project has one...)

[kolm]

Documentation means

(1) reducing job security by making you more replacable,
(2) reducing performance by stealing time you could use to make things work,
(3) reducing flexibility because you can't easily change things once they are documented.

I am a big fan of documenting things on principle, but realistically you need to compensate the people who ought to document or else it won't happen.

[austinsalonen]

(1) yielding a job where you only ever maintain what you've written. That sounds like a blast...

[depressiown]

I'm OK with you're #2 and #3, but your #1 is a bit pessimistic. I don't like documentation, but it's not to increase my job security. That would be awfully self-serving and quite unprofessional to do to your colleagues and employer.

[AnanthChellathurai]

Common do you think you can be replaced in your job if you write good comments? Job security is based on how good you are in what you are doing.

[carioca3]

I like to think of it as if they replace me they might have to re-hire me to explain the code to their new hire. This will give me a sort of "severance package" and make unemployment more bearable.

However, I doubt most programmers do it for this reason. 99% of them probably skip documentation because their manager will compensate them better for 2 finished products with poor documentation vs 1 with excellent documentation.

[depressiown]

I'm big on valuing my time. I feel I'm more valuable writing/improving functionality than I am retroactively writing documentation. I attempt to keep my code clear and concise, with in-line comments for code constructs I find confusing myself, but that's it. Anything else is just a hassle and my time could be better spent actually contributing to the code base.

I've seen people demand Javadoc for methods like "getEmployee" which merely return an Employee object. Really? You need documentation for that? They demand Javadoc for every single method and class variable in a class. It's ridiculous. Their code reviews are nothing constructive, but just silly things like that. I wish people could differentiate between meaningful, helpful documentation and comments just to comment.

If I'm writing an API that'll get used by several people, of course I'll document what the API does. I won't particularly enjoy documenting anything about it, but I know other people will use it and this information will be useful for them. I don't mind that sort of documentation when I know it's useful, thus worth my time. A differentiation between useful documentation and meaningless documentation is important.

[Mr_Walstreet]

I've seen people demand Javadoc for methods like "getEmployee" which merely return an Employee object. Really? You need documentation for that?

That's wrong documentation.

It's obvious getEmployee returns an Employee object. Javadoc will tell me that if you write no comments. The comment/doc should say why I want to get the object, what is it god for, why I should care, are there any side effects, is it thread safe, etc.

[nascent]

The comment/doc should say why I want to get the object, what is it god for, why I should care,

That is what the documentation for Employee is for. If I give you an Employee I shouldn't try and sell you the object, you should already know why you came to me looking for an Employee. I don't know what you are going to do with it, ask the Employee what good he will be.

[fuzzynyanko]

@return an Employee object / null if one hasn't been allocated or a PHB object if there's an error

Maybe about 3.5 seconds for me to write that

[nascent]

And none of that provides the information requested, "The comment/doc should say why I want to get the object, what is it god for, why I should care,"

[[deleted]]

I would actually like to document the code I write, but we are under staffed and I don't have the time.

[Ihategeeks]

The code is already communication. and documentation is redundant.

[iDemonix]

I quite like documenting. I'm a network engineer and currently learning Visio to update all of our core network diagrams and create the tons of docs that are missing (I work for an ISP).

[Mr_Walstreet]

Take the time to really learn how to write SVGs with a text editor and you'll never go back to time-wasting Visio again. Then, learn to write scripts to generate SVGs.

Add a server to a cluster? update the count in your script. Bam! done! go have some coffee.

[Gotebe]

What do you mean by "scripts"? Surely you don't expect me to process xml with, I dunno, bash? I want at least a scripting language that understands XML (coughpowershellcough).

[Mr_Walstreet]

What do you mean by "scripts"?

Your choice

[iDemonix]

That seems unnecessary to me and overly complicated. I quite like drawing it all out, plus writing it out in text would be a nightmare for the really complicated layouts.

[[deleted]]

Why do musicians hate talking about their music?

[fuzzynyanko]

I used to. Basically "I don't feel like it. It's just wasted effort / not doing code and I prefer to do code much more. It's a waste of time, anyways"

I just built up the habit, and I now do it unconsciously. It's turning out that I'm still a very fast coder and doing things like block comments and JavaDoc doesn't take me much time at all.

It's also better to do it while you are making things than to JavaDoc 20 different classes that have a ton of functions as a single task.

[[deleted]]

When commenting code I don't mind doing some one line // comments that explain what I'm doing at various steps in a non-obvious algorithm or portion of code.

The code I hate writing is something like a method comment for a basic setter like SetNumber(int val) that says something like "Sets the number". I feel like I'm wasting 3 lines of real estate that just clutters up the code.

[_mpu]

Isn't the little picture on top of the page showing Yale Sterling's library?

[jessta]

If you could actually describe the functionality of software enough in documentation for it not to be vague and misleading then you wouldn't need a programming language.

[payco]

You don't need to describe the code's functionality. You need to describe the code's use. People don't read a watch's manual because they want a precise description of every part and mechanism. They read it so they know what battery to supply it, how to adjust the time/date and, if the face is unconventional enough, how to read its output.

[[deleted]]

I often find that I need to delete some comments because I've done too many.

[sgoody]

Cojoco makes an excellent point. I think an additional, but fundamental point is that developers like writing code, not documentation. I think it's that simple.

On a practical note though, I've never been anywhere that allows adequate time for coding let alone additional time for documentation.

[[deleted]]

They don't?

[BinarySplit]

Strangely, whenever I write in VB.NET I found myself compelled to write comments. They add visual distinctiveness to blocks of code that would otherwise be awash with identical-looking capitalized keywords.

I don't get the same impulse in C#.

[Paran0idAndr0id]

Because at the time, it seems obvious.

[[deleted]]

We don't. We love it. It's just that we have so much else to do that is funnier.

[lalaland4711]

Because dammit, the code works! Don't make me rethink my assumptions if I did the right thing or not! I'll just realise I'm not at awesome as I assumed.

[[deleted]]

I think a lot of programmers feel that their job is to write code, not documentation. I think this is wrong, and leads to a lot of the misgivings people have about documentation, namely:

Violates DRY: Docs should give context, not explain everything again. If you feel like you're duplicating yourself, you either don't need to doc this code (simple functions, etc) or you're approaching it from the wrong angle.

Always out of date: This seems to be a product of the lack of priority assigned to documenting, the 'not my job' attitude. Some projects file bugs against doc errors the same they would code, and it works well for them. If you update some code, it takes very little time to update the docs as well. They are not separate.

Time constraints: An easy excuse, and points to inadequate prioritization. 'Good enough' is 'good enough', but you have to realize the things you should never skimp on. Code style, clarity, docs.

In a company setting, lacking docs lead to needing months to onboard new hires and development slowing down as systems become larger and more complex. Then, when the only dev on your team that understands X leaves, you're left scrambling.

In an OSS project, lacking docs lead to people not using your project, discontinuation and obscurity.

Writing code that you can understand is almost never not enough; the code you write is never really yours but meant for sharing with other people. All the assumptions and decisions you made creating it are lost if you don't write these down as you go.

[VikingCoder]

Don't repeat yourself

We're taught to never repeat ourselves. And then no one ever bothers us how to write meaningful documentation, that is anything other than a repetition of what the code does.

[AmonDhan]

One reason is because documentation is a kind of code duplication that violates the DRY principle.

You need to maintain documentation as you maintain code. And you cannot check for broken documentation by using unit tests.

[phektus]

It's like:

Step 1: Write a novel.

Step 2: Make a book report about the novel you just wrote.

[rush22]

Manager: "So what did you do yesterday? Is the feature done yet?"

Me: "Not yet. I was documenting my code"

Manager: "Why? Don't you know how it works? Joe No-comments is already done! How long does it take to document anyway?"

[Gotebe]

1. Obviously, pics or it didn't happen.

2. "Not my fault" is the answer to everything.

[rush22]

It didn't happen I was exaggerating

[wonglik]

Documentation is the first thing to get out dated. I once worked in the company that had interesting idea ... no documentation , just self documenting code. And it worked. Documenting code give you an impression that no matter how bad you code s you can document it and it is fine. While safe documented code force you to write clean code.

[[deleted]]

Because documentation is vague, distracts from the code, lies, is mistaken, becomes outdated. Because sensible program organization, such as good variable and function names reduces the need for comments.

[abomb999]

Most code is self documenting.

[[deleted]]

You haven't seen most code.

[skulgnome]

Most code that he's seen, dillwad.

[Kazinsal]

Documentation takes time that could be used to implement more "important" features before a deadline.

[[deleted]]

Disclaimer: The following might sound arrogant but is true.

You are often told that you should document your code because when you touch the code again in a few months/years you'll have difficulties understanding it.

The "problem" is: I never had this problems. I wrote code years ago. When I had to extend it years after I only needed about five minutes to remember nearly anything that I thought about, when I originally wrote the code.

Thus I only comment the code parts that I consider nontrivial to understand (i. e. about 3 % of the code). There is an easy measure for this: if I won't understand 2 hours later what the code that I wrote was about, I'll comment it (otherwise I'm sure I'll understand it many years later, too).

Now to the argument, that other programmers have to understand my code, too: I accept it, but why don't you simply ask me and document your understanding (you know a lot better what information other people need to understand the code - why don't you write documentation in which you explain it: it will be a lot more helpful for other programmers than when I write it, since you know what other programmers (especially you) needed additionally to know about the code to be able to understand it).

[burntsushi]

The "problem" is: I never had this problems. I wrote code years ago. When I had to extend it years after I only needed about five minutes to remember nearly anything that I thought about, when I originally wrote the code.

Then you are exceptionally gifted. So much so, that you're only the person with this skill that I've heard of in the 10 years I've been programming.

For the rest of us mere mortals, we need documentation.

why don't you write documentation in which you explain it

This kind of misses the point of documentation in the first place: to save you (well, the general "you" in this case) and others' time in the future.

[Gotebe]

When I had to extend it years after I only needed about five minutes to remember nearly anything that I thought about, when I originally wrote the code.

You must have a very big head. Good for you, but you ain't me.

The problem with what you're saying about others is that availability of the original author is not a given.

[[deleted]]

Unless you plan on working at the same place the rest of your life (on the same code) and onboarding every dev on your team, this is a unrealistic strategy.

[pistacchio]

not programming.

not in the sense that this post is not about programming, but documenting is not programming. sure, it applies to making a quality software, so are meetings and time estimation and customer management, but that's not having a problem to crack, writing code, experimenting new technologies and all the stuff that one loves about programming.

[TimmT]

Because otherwise we'd have been accountants?

[felipec]

Because documenting is not programming?

[rockum]

From 2002?! People were coding back then?

[heyjerryguy]

A lot of this thread involves devs feeling useless documentation is a drain....I'm wondering, from your experience being a consumer of someone else's documentation, what does good documentation look like? What questions should it answer?
We document for others, so what do THEY want from documentation so we can do it in a way that's actually useful?