I would never do this, but it amuses me greatly. If layoffs are imminent (i.e., management starts asking for thorough documentation of everything after a bad earnings report or two weeks before such a report is due), this article at kuro5hin describes how to create documentation that looks good but is completely useless. The very idea just cracks me up.
I hate writing documentation. I love writing code. That’s why I strive to write self-documenting code. It’s not all about comments—though I use them extensively—it’s about writing descriptive method names, filenames, and variable names. If you saw a file named “act_PutStudentOnWaitList.cfm,” you would immediately have an idea of what that file does before you ever opened it. If you saw a variable called “Session.Student.Stud_Num,” you could easily discern both its purpose and its context. Sure it results in a little more typing, but the clarity in your code makes it so much easier to revisit.
And that’s why I do it. The app I maintain (an online training self-management system, or corporate university for the buzzword-loving) was developed and is maintained solely by me. There are parts of it that I haven’t touched since the day I deployed the app three years ago. If I had to dive into those parts for some reason, I know that I could read the code and figure out what they do, how they do it, and why they do it the way they do it. I suspect that no one else will ever have to do that since I’ve been here for nine years and my self-employment is not imminent. I feel good that someone could, though.
I once tried documenting the app in conventional fashion. I got up to 10 pages of complete documentation before I was totally burned out. Unfortunately, what I produced is now stale and obsolete since I’ve added a considerable amount of features and refactored some areas to work better. And that right there is the problem with documentation that’s not in the code: it’s outdated as soon as the code changes unless you make it so general that it would apply for a long time—and then you’ve got useless documentation because it’s unspecific.
I think the reason in-code documentation is so unpopular with managers (I don’t know my boss’s position on the matter, only previous managers) is because they can’t get at it. They don’t understand how code can contain all the documentation a programmer will need because they’ve heard programmers comment on spaghetti code. Lacking any basis to understand the difference, most managers (I suspect) think the self-documenting code advocate is being lazy or trying to shirk his documenting duty. Far from it, but it’s naturally very difficult to explain to an interested non-programmer.