|
|
Re: Why is Poorly Documented Code the Industry Standard?
|
Posted: Apr 11, 2003 12:43 PM
|
|
> 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.
|
|
Previous Topic
