The Artima Developer Community
Sponsored Link

Weblogs Forum
Why is Poorly Documented Code the Industry Standard?

20 replies on 2 pages. Most recent reply: Apr 28, 2003 7:48 AM by Steve Holden

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 20 replies on 2 pages [ « | 1 2 ]
Doug Tillman

Posts: 4
Nickname: vtecinc
Registered: Feb, 2003

Re: Why is Poorly Documented Code the Industry Standard? Posted: Apr 1, 2003 6:01 AM
Reply to this message Reply
Experienced programmers bemoan the lack of comments but I've yet to see a widely agreed upon metric that translates comment-less code into dollars lost. The almighty dollar is really the only true driver of process change. Until somebody can say to a project manager, "Add a week to the timeline now for comments and documentation as the project is coded or it will cost you ?? dollars the first time we need to modify the code." Unit tests have already proven their worth and can be automated, used for regression testing, etc - there's no such mechanism for inline comments. Pre-checkin QA of comments as another poster suggested is a tough sell.

This is a topic for an MBA or MIS thesis - research on the true costs of uncommented code.

Lars Duening

Posts: 3
Nickname: larsd
Registered: Mar, 2003

Re: Why is Poorly Documented Code the Industry Standard? Posted: Apr 1, 2003 9:45 AM
Reply to this message Reply
I wish I knew a good way to instill the importance of commenting into our profession. Personally I have tried at least to lead by example, and commented my code even when I was told "Don't waste your time with it", and to later point out how much time the commenting saved not me, but also my coworkers. Ironically this usually went hand-in-hand with ignoring the company-dictated commenting standards and templates which were truly awful (I don't believe in repeating a function's parameter list in the function header comment, for example, and for 'last changed by' information I prefer source control systems).

As an aside, I am strongly suggesting that every programmer should also acquire some skills in graphic design (I like Robin William's "The Non-Designers Design Book" as a primer), as it is my experience that a lot of information about a program can be conveyed through visual composition and source layout.

Mark Wilkinson

Posts: 2
Nickname: mhw
Registered: Mar, 2003

Re: Why is Poorly Documented Code the Industry Standard? Posted: Apr 2, 2003 2:17 AM
Reply to this message Reply
I'd agree with this: I've had good experience recently using checkstyle ( to flag methods that lack JavaDoc documentation.

I've found it most useful when used as a plugin to Eclipse ( It highlights missing comments and other style issues in the same way as compiler errors. As a result I find myself trying to erradicate the checkstyle warnings before I consider my work on a class finished. Promoting lack of documentation to being comparable to compiler errors seems to bring it into the normal development process, rather than being an afterthought.

Dave Astels

Posts: 32
Nickname: dastels
Registered: Mar, 2003

Re: Why is Poorly Documented Code the Industry Standard? Posted: Apr 2, 2003 12:57 PM
Reply to this message Reply
> The act of *explicitly* writing out your thoughts forces a
> mental state that is quite different from when you just mull
> things over and then go code.

That's part of the purpose served by writing the test first. It makes you think about what it is you are trying to do.


Guido van van Rossum

Posts: 359
Nickname: guido
Registered: Apr, 2003

Re: Why is Poorly Documented Code the Industry Standard? Posted: Apr 11, 2003 12:43 PM
Reply to this message Reply
> James, I wonder what correlation there is between the
> quality of code comments and the use of unit testing in
> projects is. That is, do projects that make good use of
> unit tests, also tend to have well-commented code? If
> so, I guess this would just indicate more maturity or
> better habits of the team...

Alas, not in my experience. In one of the open source projects in which I'm involved (not Python itself, but written in Python), there's a large emphasis on unit tests, and having code without unit tests is a big sin in this project. (The only bigger sin is checking in code that causes unit tests to fail.) And yet, there's lots of poorly documented code!

There seem to be several problems here. One, design documentation is maintained separately (in Wikis rather than Word documents, but the same thing happens -- they are written before the code is written and not updated). Two, API documentation is maintained in separate interface files. This again makes it easier for the interface and the implementation to get out of sync. In addition, the interfaces are supposed to be independent of the implementation (the system architecture states that there may be multiple implementations of the same interface) and hence the interface docs don't describe quirks of the implementation that may affect the user.

But in observing closely how much of this code comes into existence, I've noticed some other reasons. First, many programmers aren't particularly good with words. Writing intelligible English sentences is hard for many of us! This is exacerbated (at least in our case) because the developer community is highly international, so English isn't their first language. Second, and perhaps most importantly, the project is under time pressure. (Aren't all projects!) This means that there's a lot of pressure to move on, get features implemented, and so on, and damn the documentation -- at least certain kinds of documentation. In other projects I've seen the same thing happen: because poor documentation doesn't express itself immediately like broken code does, writing documentation is the first thing that goes when there's no time.

Alas, this comes back to bite us many times during code maintenance: poorly documented code gets misunderstood by the next programmer who comes along, and a new feature gets added whose implementation subtly breaks some unstated invariant; or a bugfix introduces another one; etc. I've tried to emphasize the need for better code documentation, but because of the time pressure I get a lot of promises to add comments later, which of course never happens.

Steve Holden

Posts: 1
Nickname: hldnwb
Registered: Apr, 2003

Re: Thank God, the code is poorly documented(and poorly written) Posted: Apr 28, 2003 7:48 AM
Reply to this message Reply
> "An idiot can write code that computer understands;
> it takes a good programmer to write code that human
> beings understand."

This is a very good point that's often overlooked. Programs are indeed for communication between humans, but unfortunately the acid test is not "is it easy to understand" but "does it work". If the software team had goals that included long-term cost-of-maintenance issues, some programmers should be paying their employers.

You can also take heart in knowing that all the knowledge you are acquiring about how bad software is put together is also yielding you a huge list of "don't do that" features for when you move to a more enlightened employer.

Flat View: This topic has 20 replies on 2 pages [ « | 1  2 ]
Topic: SARS virus positively identified Previous Topic   Next Topic Topic: Extreme Management

Sponsored Links


Copyright © 1996-2017 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us