Fog Creek Software
Discussion Board




Why do Programmers Hate Documenting?


It's a bit of a generalization but I think there is truth in it. Many programmers, even experienced ones, really don't like documentation. Most of us do it, because we know we have to, but if we're under pressure its the first thing to go. I've reviewed code from experienced programmers with hardly any comments at all, yet we've also all tried to maintain code and cursed the idiot author who didn't add enough comments. So why do we find comment writing such a pain?

It's even worse when it comes to writing user documentation. Most of us would rather be thrown in the scorpion pit than be asked to write a manual, despite the fact that this would be the best way of showing off the brilliance of the program we wrote to a wider audience.

I have a theory, and that is that it's the 'Introvert' in the Myers-Briggs type that most programmers seem to belong to (see the Orphans Wanted article in another thread). Programmers are interested in ideas, and once the ideas are fixed concretely we lose interest in their communication.  But I could be wrong.

David Clayworth
Friday, March 21, 2003

I'd tend to agree with you David. I think most programmers have an inherent dislike for staying on the same "problem" after its been fixed (i.e., commenting the code they just wrote -- its usually incredibly obvious at that moment what the code does, so why comment?).

I find that I usually comment at my best when I comment before or during coding, since at that stage I'm still figuring out the solution etc. If I wait until afterwards, my results tend to be slapdash and haphazard.

Thoughts?

Steven C.
Friday, March 21, 2003

Usually people talk about their code when they're proud of it.  Maybe these people aren't particularly interested in their work, and it doesn't strike them to defend or promote the code.  I know that's an oddball theory, but maybe there's truth to it.

Tj
Friday, March 21, 2003

When I am writing code, it all is blazingly obvious to me right now.  In the future, someone is going to find some part of it confusing.  The problem is that I can't predict /which/ bit is going to be confusing.  So which bit do I comment?  If I comment every last line, then the comments get tedious, as mentioned in other threads.

Jordan Lampe
Friday, March 21, 2003

There is no profound reason...the answer is pretty simple: most programmers are very lazy. Writing comments is just more work. Writing a user manual is a LOT of extra work.

I have to completely disagree with this statement:
---
(re:manual)...despite the fact that this would be the best way of showing off the brilliance of the program we wrote to a wider audience.
---

I don't know anyone who reads user manuals except as a last resort , or to figure out some obscure , non-obvious feature. The best way to show off the brilliance of the program you wrote, is to actually write a brilliant program...

choppy
Friday, March 21, 2003

Hi I tend to agree with David. We consider ourself (Programmers) as an intelligent being and want to create a good new and unique things which takes us from one steo to another better steps towards our goal.  Now if documenting is driving your salary you would do that..,but it's not.  If somehow they make documentation mandatory, it  would take us forward towards the goal and hence will become and inherent part of what we do. Goal of the programmer in terms of intelligence is to increase the programming skills.  Documentation if proven to increase the programming skill we would have done that already.

artist
Friday, March 21, 2003

"Documentation is like term insurance: It satisfies because almost no one who subscribes to it depends on its benefits."
--Alan Perlis

I believe that the problem with documentation is that the people who are supposed to write it derive no benefit from it, and the people who insist on it don't have to write it.

Compare "documentation" to strong and static typing. Many programmers these days don't have a problem declaring variable types, writing assertions, or even programming by contract: they perceive that there's a benefit inherent in getting the compiler to help them write better code.

In my experience, programmers can and do become zealous about those portions of "documentation" that have a demonstrable and immediate benefit to the project, such as documenting acceptance tests.

--
http://www.braithwaite-lee.com/opinions/design-by-contract.html

Reginald Braithwaite-Lee
Friday, March 21, 2003

"Programmers are interested in ideas, and once the ideas are fixed concretely we lose interest in their communication"

I think you really hit on something there.  Sometimes, once I figure out how a piece of code should work I don't feel like even typing the code in.  The challenge is gone.  The same goes doubly for doc.  There's a strong feeling of, "I've solved this problem - I shouldn't have to still be working on it."

One-Armed Bandit
Friday, March 21, 2003

Documentation is *boring*.  Writing help files is even more mind numbing.  That's my major beef. 

I will say this though, inherting a system this well documented, especially if the domain knowledge is complex, is awesome!  It makes life sooo much easier.

Canuck
Friday, March 21, 2003

How about considering the fact that people write code that REQUIRES a copious amount of comments to be, in itself, a broken process?

Believe it or not, I write my "comments" in the form of understandable code. Variable names are good, method names are good, confusion is refactored away.

Brad (dotnetguy.techieswithcats.com)
Friday, March 21, 2003

I've repeatedly seen the claim that code can be written in such a way as to make comments unnecessary.  But in almost 30 years, I've never seen such code.  And that includes coding in hardware description languages, such as VHDL and Verilog.  Does such a coding style actually work, or is it just a rationalization for bagging comments?

Can anyone point to some examples of code that does something *non-trivial*, but which manages to explain itself to the uninitiated (say, someone who's taken responsibility for the code) without benefit of comments?

Hardware Guy
Friday, March 21, 2003

how often (assuming you are a programmer), do you actually read the documentation of an application you just bought?  not often, I would assume.  you proabably just tear open the package, click through the lengthy EULA (anyone read that?), install, and play.

programmers are lazy, who needs documentation if no on is going to read it?

we reuse code cause the thrill is gone once the problem is solved, why?  so we can get it over with and have a beer...

those who do document either do it because thier boss is looking over thier shoulder or they are just bad coders and cover it up by looking busy and productive documenting thier crappy code.

apw
Friday, March 21, 2003

Asking why programmers don't write good documentation is like asking why technical writers don't write good code.

Documentation and programming are two entirely different skillsets (although there are some people with skills in both areas).

Benji Smith
Friday, March 21, 2003

I agree with choppy in that I'd rather work to make the application/function/etc easier for the user to use than to spend too much documenting it.

The flip side is that if you start documenting it as a developer, you can wear a bit of both developer and user hats.  In many cases, I found that when I do this for either myself or others, I "find" better ways to code/display the feature. 

For me it happens when I'm trying to explain something complicated, I get frusted with the right way to explain it to "my grandmother" (my lowest common denominator target audience) and a way to simplify the interface will reveal itself to me.  Sometimes it's as trivial as showing/not showing data depending on a certain state (ie.,don't show these fields if this radio button is selected).  Other times it can be much bigger, requiring a hefty bit of reworking but resulting in a much more intuitive interface.

Chris Blaise
Friday, March 21, 2003

the code is the documentation

     
Friday, March 21, 2003

Programming is a largely a creative, problem-solving effort.  Documenting is largely a teaching and communication effort.  We like programming because we like creating solutions to problems.  (Some of us like finding the solution so much that once we've figured out the solution we're not interested in implementing it!)  We don't like documenting because we feel like we're not really solving a problem, we're just describing something.

Also, I think a lot of programmers view documentation as largely being a waste of time and effort.  When you are writing the equivalent of, "To create a new document click 'File', then 'New'," the thought going through your head is what a colossal waste of your time this is.  After all, anyone can figure out how to do simple things, right?

I don't believe the claim that programmers are lazy.  I do believe that programmers dislike doing things that are not programming.  Like writing documentation, working on schedules, defect tracking.  And we'll procrastinate on those things, or do the minimal effort necessary.  That's an ego thing.

-Thomas

Thomas
Friday, March 21, 2003

"I've repeatedly seen the claim that code can be written in such a way as to make comments unnecessary.  But in almost 30 years, I've never seen such code"

I think this depends on what you're looking for. I think when people make this assertion, what they're saying is "if you write good code, then it won't be too hard to figure out". I suspect what you are looking for is something that tells you what the code is doing before you even get into it.

There's also the issue that code is understandable *in context* or to someone with a system-wide view, but yeah it may take some more work for the "hit and run" debugger. The description from Unmanageable Code is "they are viewing your code through a cardboard tube; they don't have time to understand the application"

I think if you're trying to debug an app without getting into it and understanding the application then you're asking for trouble.

Finally, an example of how well-written code can obviate commenting - in the spaghetti code days comments were essential in a ten-page module to indicate what's happening where. In procedural programming the procedure names should replace the section-level comments. Instead of
//Now we fill the bill of materials display for the order id requested

you have
public void FillBillOfMaterials(int OrderID)

Philo

Philo
Friday, March 21, 2003

I'm with Choppy and Chris: One book I read said that every user manual is a list of design mistakes.

One benefit of code and design reviews is that anything too complicated to explain to smart people is quickly discarded.

Perhaps reviews are a form of disposable documentation?

Since the benefit is in the explaining but not the explanation, a review offers the "lowest barrier to entry" form of documentation...

--
http://www.braithwaite-lee.com/opinions/clothes.txt

Reginald Braithwaite-Lee
Friday, March 21, 2003

Programmers probably hate documenting for the same reason that teachers hate keeping record books, and computer users hate having to fiddle with their computer; they're in that particular line of work because that is what they like and not the other task .
In my experience peoiple who know how to do things the best are not always those who can explain it the best. There's no greater block to explaining something than thinking its obvious, and for the better the programmer the more obvious many things are.

It's why large companies have technical writers. The question of  commenting code is slightly different; the thread lower down seems to have dealt fairly well with that. That is to say that code might document itself, but you still need comnents on the why, and on what is not there.

Stephen Jones
Friday, March 21, 2003

1.  The code is not documentation
2.  Good coders document.
3.  If you don't document you are AUTOMATICALLY a bad coder.

Nuff Said
Friday, March 21, 2003

"Nuff said" - you should look into this thing called "supporting arguments." They help. A lot. Think of them as comments for your debate....

Philo

Philo
Friday, March 21, 2003

Read Code Complete

Nuff Said
Friday, March 21, 2003

Going along with what Philo said -- the best description of what some programmers do is "comprehension free coding". That is...well pretty much what it sounds like: trying to fix a problem without understanding the code surrounding it.

Now I don't want to discredit this entirely, since in large projects you have to do SOME amount of comprehension free coding -- i.e., assume that the rest of the system works in a good way, and fix the problem where you've found it. To be sure, too little comprehension will be a disaster -- but especially when you have people who are just joining a team working on a large software project, you have to expect that some of their work will of necessity lack the overall comprehension that someone working there much longer may have.

Good comments, in general, allow less "overall" understanding and thus faciliate this fixing style -- which is good, I think, especially if you want your software to be maintained by people far into the future.

But mostly, I just like to make fun of people for doing "comprehension free coding". I just get a kick out of saying it. :P

Steven C.
Friday, March 21, 2003

To add a different twist (and to reiterate something else someone said), comments come from the days of long, hefty code.

Most methods do waaaaaay too much. Refactor. Methods should have no more than a handful of lines of code, and a single discrete tasks. Those "big blocks of code" will then generally become calls to these smaller methods.

We've all heard that any time you see duplicated code, you should pull the common code out into a method. I'll go farther to say that after you've done that, then go ahead and pull out small, discrete units of work (perhaps no more than 10 lines of code) and make those methods as well.

At least in the environment in which I work, there is an effectively zero penalty for non-virtual method calls. All can be inlined in real-time by the JITter. And even if I pay a dozen nano-seconds for the method call, that's infinitely better as my servers get faster, compared to the minutes or hours I (or others) might have to spend understanding code. Our PCs continue to scale, but we developers do not.

Brad (dotnetguy.techieswithcats.com)
Friday, March 21, 2003

Nuff Said - you're missing the point. Throwing out mantras and appealing to authority can be the equivalent of what some people are trying to suggest here - that doing a thing because "this coding god said so" and "that software bible insists" does not make one a good coder, and can in fact be a crutch that keeps one from being a good coder.

If the absolute truth is "without comments one cannot write good code" then it's a subtle twist to "comments can make one's code better" therein creating a reliance on comments to accomplish what can be done with editing, optimization, and refactoring.

A comparison of two "does this appointment conflict with any existing appointments" routines:

[in pseudocode]
1)
CheckAppt(datetime start, datetime end)
  //Check Appointment takes two datetime variables
  //which are the start and end of the appointment

  for i=start to end  //let's step through the appt
    //here we create a cursor of the days of each
    // appointmetn that this person has
    select cursor=days
    from appointments
    where personid=currentuser

    //now we step through the cursor
    //and compare each day to the current day
    // in the appointment
    for each day in days
      if day=i then return "Has Appointment"

    //go to the next day
next i
End CheckAppt  //end procedure

Or...
2)

CheckForConflictingAppointments(datetime startdate, datetime enddate)
    Select 1 from appointment
    where appointment.start<enddate
        and appointment.end>startdate
        and personid=currentuser

    if(records.count>0)
        return "Has Appointment"

End

Is procedure 1 really so very much better because it has comments? Does procedure 2 really need comments? I'll wager that if the person who wrote 1 focused on why they felt they needed comments instead of writing the comments they may have gotten to 2 in the end...


Philo

Philo
Friday, March 21, 2003

I think the answer to why programmers hate documenting is obvious... writing documents is not nearly as much fun as writing code.  I think more important questions are what documentation should programmers be writing and how do we motivate them to write it.  I argue that code comments and functional specs are essential, and most of this content should be written before the code.  If you can't describe what a function is supposed to do in English, then you don't have the knowledge to code it yet.  I wish I knew how to motivate programmers to do this, as this is a problem I am facing in my group as a QE desperately in need of useful functional specs.

Master Ninja
Friday, March 21, 2003

I hate writing comments even though I love to write. I have previously been a teacher and I really like explaining things to people. And I was a researcher and I loved writing research papers. Therefore, I should like writing documentation or comments, but I don't, I hate it.
It might be, as someone said, because it's so hard to guess what parts of the code will be obvious to others and which will not.
The managers where I work are programmers also and they hate writing comments, so they forget to make us do it, so it hardly ever gets done.

The Real PC
Friday, March 21, 2003

I don't thing being introverted is related to it. My understanding is that most authors are introverts. Sitting down and writing documentation or a book is low on the list of interests for most extroverts.

Introversion is a concept misunderstood by extroverts. It doesn't necessarily mean shy or unable to deal with people. It means one is comfortable with the company of one's thoughts. Introverts can do great at parties if they want to, contrary to popular prejudice. Many hollywood actors and actresses are introverts as well - INTP in particular is very well represented in Hollywood.

Dennis Atkins
Friday, March 21, 2003

I never understood the business about coders having such a hard time with comments.  For me, commenting is part of my thought process.  I write the comments to document the purpose of the next block of code before I actually hammer out the code.  It helps me figure out what I want it to look like.  Maybe I'm just the odd one out.

jb
Friday, March 21, 2003

As a user I have an emotional reaction whenever I read a manual/helpfile (online, or printed) and I find chunks of text such as:

To set the color of page text and
background:

  1.Open the Edit menu and choose
  Preferences.

  2.Open the Appearance group and click the Colors category.

  3.Click a color button to change colors of text, background, unvisited links, or visited links.

  4.(Optional) Click other checkboxes as desired:

      "Use Windows colors" ("Use default colors" on OS/2, Mac OS, and UNIX) to restore the original colors.

      "Underline links" to make links easier to find.

The emotional reaction I feel comes with a thought attached to it: "Why doesn't the moron who wrote this doesn't merely say 'On the menu bar, click on Edit| Preferences| Appearance| Color, and customize to your heart's content'--instead of making me read grating lonnng sentences to say something stupidly simple."  To be safe with complete L-users (L = learning), a hyperlink on "click on" would suffice to explain there the notation "click on xxxx| yyyy| zzzz|."

I can only imagine the emotions and thoughts that would invade me if I had to perfunctorily pipe "good idea" to a manager that would arrogantly require me to write a manual as quoted above.  Quite likely my private thoughts would be "what an unbelievable cretin!"  And writing such manual would be a bitter transaction for my livelihood.

As a further observation, I find it extremely annoying and stupid to find entries in a manual that merely restate in other words what the evident meaning of a label of a widget in a GUI is, such as "to restore the original colors" in explaining the pushbutton labeled "Use Windows colors."  Isn't it easier to "write what you mean" for a label, thus obviating an explanation in the manual?

*sigh*

__Felix Somnia__
Friday, March 21, 2003

The problem with this kind of argument is that there's always enough strawmen to feed a large herd of cattle. If all you do is write code which is simple enough to be self documenting, then you should be fired and replaced with a college intern.

In particular, comments should be used to inform the reader of things like pre- and post-conditions for methods, the intended use of variables, and anything else which might be non-obvious to someone other than the author (including the author a year from now).

For example, Philo, in your conflicting appointments method, you appear to be making the assumption that the dates you have are in the same timezone as the dates stored in the database. For a more complex method, there are often questions like "is null a legal argument here? what meaning would it convey? Am I allowed to modify this data structure?" etc.

Of course you shouldn't comment every line of code. In fact, for most methods you only need a single comment describing the intended use and parameters. But any real-world system will have plenty of cases where explanatory comments are helpful and greatly reduce the time spent maintaining the code, especially by reducing bugs introduced by the maintainers through misunderstanding.

Bryan
Friday, March 21, 2003

Philo, your example is a poor example for saying that good code doesn't need comments, because those are extremely bad comments.  I think everyone can agree that commenting on things that are obvious from language constructs or variable/method names is extraneous and should be left out (ie, the "X function takes two parameters" or "Start looping over X").  However that is just one class of comments.

As for the idea that good code documents itself, to some extent I agree.  Appropriate factoring and good method/variable naming goes a long way toward making the code readable without comments.  But there is one thing that the code itself can not answer, and that is *why* it does something, or why it works the way it does.  This sort of commentary on design decisions made by the previous coder can be invaluable.  Other things that should be well documented are invariants, and why they should hold/why they make sense.  When possible, of course, these can be documented using code such as asserts

The other problem with the "good code documents itself" stance is that, if the code doesn't do what was intended (ie, there is a bug), there may be no way for a future developer to know what the code was *meant* to do.  Sure your code is very clear about what it actually does, but I don't care about that when what it actually does is not the correct behavior.  What something is *supposed* to do, and does incorrectly, can be very difficult to gleam unless there are comments discussing the intent of the programmer.

Mike McNertney
Friday, March 21, 2003

More generally, I think a lot of programmers hate to write prose.

Why? I don't know. I think there's a certain culture of "functional illiteracy" in some programming circles. It's almost a blue collar attitude of being a 'specialist' who is held exempt from communicating concepts or ideas. I've known programmers who were quite proud that they didn't understand basic text formatting in a word processor and that any memos they did always looked sh*tty.

Sometimes I think that certain stereotypical pet phobias like this held by programmers cause the rest of the business world to roll their eyes at us as "oh, THOSE losers".

My belief is that real professionals, by definition, WRITE. Professionals write: overviews, documentation, communication to peers, clients or management. And code comments.

And I'm not talking about some featherbedded crap where you write a 15 lb treatise to  document an action plan to have a meeting to plan a new internal application... That's *always* the feeble strawman excuse of those who have developed a phobic reaction to writing - a blather that they're not working in DOD or for the space shuttle or whatever, so they "can't" be expected to write (poor babies).

I just mean that someone being paid at the kind of salaries or rates prevailing in this industy really should be able, ONCE in a while, to write decent and understandable prose that informs others as needed. The idea of a person earning $80,000+ / year exempting themselves from communication with others is ridiculous.

If someone in this field does not want to write and is even proud of not writing... then accept the consequences. One of which is that nobody in management will believe that you know what you're talking about.

Bored Bystander
Friday, March 21, 2003

per godwin's law, this thread has devolved from "huh?" to "what the fuck?" I'll do my part to make it even more pointless.

my dad is a "professional" obstetrician and makes about five times as much money as I do. i'm pretty certain he has not written any sort of prose since he was a college undergrad. he can't type and can barely write, so far as i can tell. i don' think anyone else in his field cares.

marginally related, the last time I had to spend a significant amount of time writing documents was when i was working in an academic lab after graduating from undergrad. in fact, we never really accomplished anything in that lab,other than accumulating millions of taxpayer dollars through approved grant applications. since i've been a programmer in the "real world" i've never had to write any sort of prose again, so i'm wondering where you pro-prose people actually work, and what you are talking about? I'm all for communication and yes, comments in the code are usually good, but writing a user manual or random word documents has usually been the job of a technical writer, not a programmer...

choppy
Saturday, March 22, 2003

I agree that the code itself is the best documentation.  It's hard for beginners to wrap their heads around a large body of code, but if you want to know how a program works, reading the code is the best way.

jc
Saturday, March 22, 2003

There's a useful distinction that can be added to this discussion - the distinction between documenting the code, and writing user manuals. They're quite different things.

Programmers generally don't want to write user manuals because they find them boring. Also, some can't write well, although by no means all. Generally, though, preparation of user manuals is best done by people who take a pride in that job.

Regarding documentation for code, I personally favor the concept of literate programming - self-explaining code. There are occasions when this should be supplemented by notes.

As someone above pointed out, "comments" along the lines of: "Takes two parameters ugh and oh and returns an int" have no place in quality work.

3
Saturday, March 22, 2003

So Philo provided a bad comments sample. Can someone provide a code sample with good comments, please? With good comments which can not be removed by writing the code a little different?

Thomas Eyde
Saturday, March 22, 2003

My biggest problem with documentation are requirements like "...and it has to be documented!". No indication on indended users or usage, nothing on what it should describe. Nothing.

Too many customers require documentation, but have no clue on what should go into it. We are programmers, not magicians or mind-readers. And I don't like to waste my creative energy on guessing what the customer needs. I need the energy more elsewhere.

Thomas Eyde
Saturday, March 22, 2003

The conclusive reason why programmers hate documentation: It's wasteful, and most programmers hate anything that doesn't have a purpose.

When I say wasteful I don't mean that it doesn't serve a purpose, but rather that without a strenuous committed, time sucking process the documentation can be more of a hindrance than a help as it diverges from the actual purpose and function of the code to being completely separate reality. Many help files and programs share very little in common.

How do you solve this quandary? Through the use of tools and technologies that eliminate duplications of effort and divergence. For instance if you have a UML tool that comments your class diagrams, inserting them as comments in the code, and then another tool pulls the code comments and creates a nice WinHelp or HTMLHelp or PDF, then THAT is a process that coders can work with (and it'll yield much better results). Manually synchronizing things NEVER works over the long run.

Jimmy Chonga
Saturday, March 22, 2003

As far as commenting your code, the answer is yes you should do it. It will help when you come back to it later. And it will help others when they have to fix your bugs. I guess though the super geniuses whose code not only is bug free but prefectly meets current and future requirements are exempt from writing comments. I even put comments in one-off utility code that I know for a fact no one will ever look at again. The comments help me design and structure the code. Perhaps if you have separate design documents that specify everything in advance before you start coding you can skip the comments. Perhaps.

But what I really want to talk about is the issue of user manuals. I write user manuals for all my applications. It's the very first thing that I write in fact. The user manual IS the requirements document in my style of writing. It works for me and I think it's a very good way of doing things. I suppose it takes all kinds but honestly you need to have somebody on your team that can generate plain talking easy to understand documentation that explains what the program does. maybe its a fancy pants pdf file with embedded this and that or maybe its a plain text man page. Whatever it is, it's real helpful to have a high level view of what you are doing to help stay on course. It's also great reading for customers and investors. Just last week, one new client said one of my manual's was one of the most intriguing and compelling things he had ever read. yeah, OK, I work some sales talk and rah rah in there as well. Why the hell not? It's all part of taking over our segment of the industry and leaving our slow and dimwitted competitors far in the dust behind.
 

Dennis Atkins
Saturday, March 22, 2003

This thread and the comment thread have something in common: most of you are where I used to be. I used to be a stickler for commented code.

Then I started learning and using refactoring. This was a real eye-opener, that you could make the code speak for itself instead of needing comments. I read "any time you find yourself writing a comment, refactor instead". It sounded like crap when I first heard it, but I started doing it anyway, and it's absolutely true.

Someone posted that they wanted to see code that had perfect comments, that couldn't be divorced from the comments. Other than explaining the "how" of an algorithm (like, say, describing how an encryption system works), I've yet to see this. I can't promise I have the time to do it, but if someone posts something they think qualifies, I'll give a shot at refactoring out the coments.

Brad (dotnetguy.techieswithcats.com)
Saturday, March 22, 2003

One more time: can anyone point to a *non-trivial* example of self-documenting code?

If self-documenting code can be written, I'd like to try it myself.  But I need something more than assurances that it's possible.

Hardware Guy
Saturday, March 22, 2003

Well, I don't know how old you are but likely I was refactoring since you were in diapers. And writing comments. Good ones.

"In our olfactory analogy, comments aren't a bad smell; indeed they are a sweet smell. the reason we mention comments here is that comments are often used as a deoderant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad." -- Martin Fowler, Refactoring, page 87

See, it's not that comments are bad. Your argument suggests you believe that not writing comments is a mark of brilliance because some bad code has comments. This is like saying that because some meat is spoiled, everyone should be a vegetarian.

Dennis Atkins
Saturday, March 22, 2003

Brad, I accept your challenge. Please refactor the following FFT code to make it easy to understand without comments:

import java.awt.*;

double[][] fft_1d(  double[][] array )
{
        double  u_r,u_i, w_r,w_i, t_r,t_i;
        int    ln, nv2, k, l, le, le1, j, ip, i, n;

        n = array.length;
        ln = (int)( Math.log( (double)n )/Math.log(2) + 0.5 );
        nv2 = n / 2;
        j = 1;
        for (i = 1; i < n; i++ )
        {
                if (i < j)
                {
                        t_r = array[i - 1][0];
                        t_i = array[i - 1][1];
                        array[i - 1][0] = array[j - 1][0];
                        array[i - 1][1] = array[j - 1][1];
                        array[j - 1][0] = t_r;
                        array[j - 1][1] = t_i;
                }
                k = nv2;
                while (k < j)
                {
                        j = j - k;
                        k = k / 2;
                }
                j = j + k;
        }

        for (l = 1; l <= ln; l++) /* loops thru stages */
        {       
                le = (int)(Math.exp( (double)l * Math.log(2) ) + 0.5 );
                le1 = le / 2;
                u_r = 1.0;
                u_i = 0.0;
                w_r =  Math.cos( Math.PI / (double)le1 );
                w_i = -Math.sin( Math.PI / (double)le1 );
                for (j = 1; j <= le1; j++) /* loops thru 1/2 twiddle values per stage */
                {
                        for (i = j; i <= n; i += le) /* loops thru points per 1/2 twiddle */
                        {
                                ip = i + le1;
                                t_r = array[ip - 1][0] * u_r - u_i * array[ip - 1][1];
                                t_i = array[ip - 1][1] * u_r + u_i * array[ip - 1][0];

                                array[ip - 1][0] = array[i - 1][0] - t_r;
                                array[ip - 1][1] = array[i - 1][1] - t_i; 

                                array[i - 1][0] =  array[i - 1][0] + t_r;
                                array[i - 1][1] =  array[i - 1][1] + t_i; 
                        } 
                        t_r = u_r * w_r - w_i * u_i;
                        u_i = w_r * u_i + w_i * u_r;
                        u_r = t_r;
                } 
        } 
        return array;
} /* end of FFT_1d */

Dennis Atkins
Saturday, March 22, 2003

OK, I'll tone it down.

Usually - management imperatives to document code are nonsensical and Dilbertish.  I'll agree with that wholeheartedly. In fact, the directives to document are do thoughtless they're just plain stupid.

"Document it so we can get a trainee or clerk to understand it." "But it's really complex, how do you suggest I document it?" "Make it clear, you techies are always making things too hard." Etc.

But telling someone "the code will tell you everything you need to know" is often unfair, arbitary, and is a mask for laziness and unprofessionalism. I've found that only trivially small applications can be reliably understood by examining uncommented code.

And when I rant about the need for written communication I'm also ranting (by implication) about tendencies among most geeks to not want to explain anything or break anything down into simpler concepts.

Case in point: last year I did a turnkey contract that consisted of porting a 100,000+ line piece of avionics code into a training simulator. I could find *NOBODY* in that organization that would bother to give me the time of day to review the basic operational concepts of the existing software.  Even SW people that knew couldn't begin to even describe lucidly what the general operation of the thing was.

The point is, the inability of my "peers" to support the work with even a token level of overview of major subsections of the thing did several negative things. It probably added 2-3 months to the task. It made me less sure of the architecture, to the extent that I had to guess why things worked. It reduced my productivity greatly because I had no idea how interconnected different parts of the whole were. My work was less effective overall because my self described world class peers were functionally illiterate about conveying ideas.

In fact, most tech workplaces with legacy code tend to resemble frat house hazings. It's considered a badge of honor and necessary dues paying to be unproductive while you re-invent the wheel.  You're swimming in mud trying to get some traction while a bunch of oafs that *know* willfully withhold information, your lifeblood.

This unwillingness and lack of ability to communicate concepts to peers or management is woefully rife in this industry.

Bored Bystander
Saturday, March 22, 2003

I pretty much agree with the code being the best documentation. 

That said, there's good code and bad code.

Bad code, like the example Dennis Atkins provided, is usually accompanied by bad comments, again, like the example Dennis Atkins provided.

Good code usually doesn't need the comment. 

Caveat:  I'm a fan of a 1-liner 'why' comment every now and then.

slacker II
Saturday, March 22, 2003

Everybody can be upset with me if they read vitriol into what I wrote. I was just pointing out that the people who are militant commenters may be better served by learning to refactor than learning to write longer, more prosaic comments.

I didn't claim to be brilliant or superior to anybody here (I don't know you, you don't know me; how could anybody make such  a claim?). I was merely trying to point out to people that there's life after "novellas of comments".

As for the FFT sample, we have two problems. First, I don't know what an FFT does (sorry, no math degree), and second, that code is not really commented in any significant way to help me figure it out. Besides which, I think I pointed out that I find there to be a general exception of comments to descibe the "how" of algorithms. A purely mathematical algorithm -- which occurs pretty rarely in most code -- is probably going to require comments. *shrug*

I'm not anti-comment. I'm pro-refactoring as a way of getting readable code. Comments are often covering up bad code (as a previous posted pointed out), but just as often, they're out of date and inappropriate.

As for non-trivial code that has little commenting, I can't post the code I'm working on right now for obvious reasons. As of today, it's approximately 4550 files broken into 4 projects, covering about 3.5 megabytes of code (we haven't released v1 yet). Well over 98% (at a guess) of the comments there are XML comments for auto-generating help files.

Look, everybody can be pissed off all they want. I'm not really interested in a pissing contest with anybody. My offer stands to attempt to refactor out the "perfectly commented" bunch of code that somebody brings. I'm afraid the FFT example doesn't really work for me.

Brad (dotnetguy.techieswithcats.com)
Saturday, March 22, 2003

Brad -

We're not pissed off with you (at least I'm not).  We're just not convinced.

It's not your job to prove that someone can write good, self-documenting code.  Nor is it our job to believe you, at least not without a little proof.

Hardware Guy
Saturday, March 22, 2003

Ahem. Well that Java FFT routine I cut and pasted from the web is not all that optimized, but it's a pretty decent one pedagogically. It's laid out pretty clearly and concisely. The variable names seem clear to me since I have a general idea how the FFT works. I don't see any point in documenting it further, it looks good as it is.

I think you are sort of getting my point and sort of not getting it. i'm really with you on the refactoring and agree with what I posted by Fowler -- a lot of comments might be a bad smell indicating the code could be refactored. but fowler never says you shouldn't comment - he says commenting is a sweet smell, meaning he fawors it and sees commenting as good.

On the FFT, comments added would tremendously help someone who was not intimately familiar with the FFT understand it a lot better, and maybe even enable them to do some optimization or tweaking. Most code is this way. Most code is obvious to the person who just wrote it today, and much is obvious to someone who is intimately familiar with the problem domain. Even so you should still comment since not everyone dealing with the code is going to be that familiar with it. And for many other reasons too.

Dennis Atkins
Saturday, March 22, 2003

Perhaps you didn't understand my point about self documenting code. Variable names like a_b are hardly self documenting. And a mathematical formula is a little bit outside the scope of self-documenting anyway, as I pointed out earlier.

Done posting. Good luck. Write novels of comments!

Brad (dotnetguy.techieswithcats.com)
Saturday, March 22, 2003

The other thread on commenting code seems to state it pretty clearly.

You don't comment primarily on what is in the code. You comment on what isn't in the code (the why, the business case it's trying to address, the reason for doing it this way and not another, any pitfalls to watch out for when refactoring, and so on).

I really fail to see how refactoring is going to make those comments redundant.

Also one or two line comments at the top of each short block of code saying what it does, so you don't have to read it all can be useful. You could use meaningful names instead but do you really want controls called

PrintReportToShowHowManyApplicantsFromCountrySpecifiedinCountryOfCurrentResidenceDialogBoxArrangedInReverseChronoligicalOrderofApplicationDateButton

Stephen Jones
Sunday, March 23, 2003



Maybe it's the mathematical mind at work.  As One-Armed Bandit said, "Sometimes, once I figure out how a piece of code should work I don't feel like even typing the code in."  This reminds me of a joke I once heard:

An engineer, a physicist and a mathematician are staying in a hotel. The engineer wakes up and smells smoke. He goes out into the hallway and sees a fire, so he fills a trash can from his room with water and douses the fire. He goes back to bed. Later, the physicist wakes up and smells smoke. He opens his door and sees a fire in the hallway. He walks down the hall to a fire hose and after calculating the flame velocity, distance, water pressure, trajectory, etc. extinguishes the fire with the minimum amount of water and energy needed. Later, the mathematician wakes up and smells smoke. He goes to the hall, sees the fire and then the fire hose. He thinks for a moment and then exclaims, "Ah, a solution exists!" and then goes back to bed.

Another way of stating it: "The proof is left as an exercise for the reader."

ODN
Sunday, March 23, 2003

I dont mind writing some small document to go with my code if its needed. Usually if you do document an api half a page of text per function is plenty. However most places I have seen use totally bloated templates for documentation purposes. These templates usually are one-size-fits-all, used for all program documentation needs regardless of platform, which renders 70% of the template not applicable because it deals with say mainframe related stuff, and Im documenting UNIX stuff.

Short and sweet goes for code. Short and sweet should go for documentation as well. Templates are so stupid it is laughable.

This is why I hate writing docs. And needless to say, why people hate reading it.

Patrik
Sunday, March 23, 2003

Where's the proof that someone can't write good, self-documenting code?

simple mind
Sunday, March 23, 2003

this is self documenting code:

http://www.cis.ysu.edu/~kramer/DataStructures/Intro/SelfDoc.html

simple mind
Sunday, March 23, 2003

McConnell shows you how to do it:

http://www.construx.com/survivalguide/doc/chk17.htm

simple mind
Sunday, March 23, 2003

I have a simple explanation:

Writing comments is different than coding, and requires a different set of skills than writing code.  Developers have no more tendency to enjoy writing comments than they have a tendency to enjoy acting.

So, developers just don't like writing comments.  Why *should* they like writing comments?

Brent P. Newhall
Monday, March 24, 2003

We programmers want to be little gods, creating something that does something, that "lives" somehow.
Documentation is dead matter in this sense.
Another point is:
With documentation you never can be shure when you're done. You have no real requirements that are easy to verify.
I at least like to have test cases: They tell me exactly when I'm done.

AW
Monday, March 24, 2003

Another chorus of this song:

http://c2.com/cgi/wiki?CommentTheWhy

Danil
Monday, March 24, 2003

Ever read your own code (say after a few months) and
thought "Boy, that was smart!" or "WTF?!"

This experience has taught me to comment code that I anticipate will be tricky for me to figure out later.

However, because it doesn't happen that often, i.e I find my legacy code fairly easy to follow, I'm frugal with comments in code.

I figure anyone that has more difficulty understanding my code that I do, has no business reading my code.

Tinashe Rondozai
Tuesday, March 25, 2003

Writing source comments isn't bad. The trouble is updating them when the code changes. Source can change a lot in the first cut, and no comments are better than misleading ones.

I have just found this out *again* on my current project. Had to change the operation of a server to fix some bugs, and well , any original comments are just not good.

Actual real documents are a complete pain. Ditto the updating part. Noone reads them either. Developers are frequently under so much time pressure that they have to optimise, and documents that don't get read are the first to go.

Richard
Tuesday, March 25, 2003

On the FFT algorithm: I think there's a lot that could be done to clarify this code.  I've not actually done it, because I've not the time to put together a test harness, but the obvious refactorings:

(1) Change the input and output types from double[][] to ComplexPolynomial (you can then pull the double[][] out of that, to preserve performance)

(2) offsets should be REAL and IMAGINARY.  Similarly, _r and _i should be renamed.  Assuming that performance requires that these all be worked with as raw doubles, rather than a clarifying Complex type.

(3) unless I'm missing something, that first for loop can be pulled into its own function - BitReverseCopy

(4) The rounding functions [ (int) (foo +0.5) ] can be pulled out

(5) I'm skeptical, in general, of the lack of function calls.  Especially in the parts of the routine that are O < O(n log n).  Would need a realistic performance harness to verify that, of course.

Danil
Thursday, March 27, 2003

*  Recent Topics

*  Fog Creek Home