Summary
Perhaps bad and nonexistent documentation is to be expected -- there isn't even agreement that it is important.
Advertisement
Perhaps bad and nonexistent documentation is to be expected. Ever seen good code comments in a book? Ever heard a programmer being praised for well commented code? The best you can hope for is a smattering of mind-numblingly dull and ridiculously incomplete Word documents that are a year or more out of date.
We are used to the culture of making others dig thru the dirt. It is considered a badge of honor to decipher how a piece of code works and should be used. There was a time when such things were interesting to me, but now I'm tired of the cat and mouse game.
The GTSL* argument is that the code is the documentation. Unfortunately, the code is not the truth. It is full of lies, deceit and broken promises. Looking at the code, it is quite easy to follow the wrong path.
I guess I shouldn't be too surprised or dismayed by this; after all, is good commenting taught in schools? Are there any books on the subject? Even books that talk about programming style often let you off the hook by saying that it is even more important the code should have meaningful variable and method names than thorough comments. I think this is often interpreted as "comments are not important." Even for those few who make a concerted effort to have meaningful variable and method names, comments are still important. Unfortunately, many people don't even do that, yet still assume the comments are unnecessary.
The only place I have ever seen reasonably well-commented code is in professional APIs and components. Despite complaints about Java API documentation or Windows API documentation, at least there is some.
How can we instill some sense of responsibility to write clear and well-commented code in the average programmer?
Almost every time I've bemoaned the lack of comments or documentation I'm told to "read the source." Even if the source uses truely descriptive method and variable names, the source can only tell you what a program does, not what it is supppose to do or why it should be doing it.
Many of the excuses people give for not writing coments remind me of reasons why people don't write tests: Takes too long; I don't have time; doesn't contribute to the shipped product; I don't need them.
Yet, just as test-driven development (often) leads to better-designed code, I've found that comment-driven or comment-first development also leads to better code.
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. Comments are as valuable to the person writing them as the people reading them.
I think that the only way we can ensure programmers to write clear and well-commented code is to:
1. Select a toolset which give the programmer himself/herself added value.
2. Verifying the quality of the code in a pre check-in process to the repository.
The second part is fairly easy to implement (basis level at least) in an organization.
To support the added value, I think we have to look at something like xUnitlet, i.e. a way to formalize the documentation so we can make a tool which auto-generates a fair amount of quality unit tests for the system.
> 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. Comments are as > valuable to the person writing them as the people reading > them.
I quite agree. A colleague of mine, when "questioned" about a lack of comments in his code replied that writing comments took too long because he always changed his mind halfway through writing a method as to what it would do. He didn't like to have to go back and re-write his comment!
I pointed out to him that if he took a little time to think about what the purpose of the method was before he wrote it he would be less likely to make significant changes to it's purpose. A good aid in doing this? Write the method comment first of course :-)
The other issue to come out of this though is that the developer in question believed the comment should describe the implementation of the method rather than it's purpose and how to use it (i.e. params, return values and exceptions).
I believe this is a very common mistake. A comment which describes the implementation rather than purpose and use is a waste of time! I can see how it's implemented more accurately from the code. I think this misguided approach to comment writing is often the cause of the often used, "the code is the documentation" excuse for not writing comments.
Several years ago a fellow student at university showed me some code he'd writen for an assignment. He was very proud of the code because he claimed he'd commented it really well etc.. He'd written a comment for every single line! I didn't know whether to laugh or cry when I read the comment, "/* ha ha does what it says! */"!
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...
Thor's comment on tools reminded me that I wanted to point out that lack of comments is even more inexplicable in an age where we have things like JavaDoc, or .Net's (much inferior) copy of if, which allow you to automatically generate nice documentation without ever opening a word processor. That's outside going to any special effort to use more advanced tools. Making use of these facilities is practically effortelss and the payoff seems quite large, to me, so I am really perplexed by completely comment-free code in Java, C#, Python or any other language that has virtually built-in comment-generation facilities.
Paul, I couldn't help but chuckle when I read your stories. They do point out some serious problems in the way people think about comments. I hadn't considered the idea that the reason why so many people disdain writing comments is that they consider them redundant. If your comments do nothing more than explain the implementation, then they are mostly redundant and you are justified in not wanting to write them.
This goes back to the lack of education on the subject. Lacking education, I think one good way to approach commenting is to ask yourself what you would want to see if you found this source file and knew nothing about it. What does it do? What is it for? What assumptions does it make? Who is its intended audience? Who wrote it? When was it started? Another additional way to think about it is, if it were a professional API, what would you expect?
I think there are great benefits to the comment writer as well as the reader. I have had the experience of changing my design as a result of writing comments and I thought that was a good thing. I would prefer to have my code influenced by the thought that takes place when explaining and rationalizing it. Usually at that time you can more easily spot inconsistencies or higher-level flaws that will escape you while your head is buried in the code.
I can think more abstractly and clearly in English than in most programming languages. I like writing, though. Programmers are often stereotyped as not liking and not being good at it. Whether that is true especially of programmers or just people in general is another question.
If all the code is perfectly documented/written, why do you think your employer would pay you big bucks? Unmaintainable code is a gift from God for all the programmers ;). You might think differently if you're an employer.
If you make a living for selling umbrellas, don't you hope it rains everyday?
All in all, the conflit of interests is the root for unmaintainable code.
I don't buy the "Job Security" argument. I think it is just a cop-out. I think if you have good coding and documenting habits, it is too painful to intentionally do a bad job.
I also think there is plenty of work to do for good programmers; it isn't necessary to intentionally make your code impossible for others to maintain. Unfortunately, too few managers know enough about the code, but I think that you can't write poorly documented, poorly structured and difficult to maintain code while still delivering good results on time. While I don't decry managers for not reviewing the code themselves, they can take the initiative to try and gain some awareness of code quality, by discussing it with their teams and perhaps even occassionally soliciting the opinions of experts.
The biggest example of this in my experience was on a project where they hired a specialist for one area because they didn't think anyone on the team had the specialized knowledge. After about six months and no results on not-very-difficult problem, they asked me to take it over. I was in state of shock and horror when I tried to decipher that code. It was truly byzantine, the worst I had experienced. I was even more shocked when it became clear that solving the actual problem was pretty trivial. Since it was primarily done with a third party library, so no special expertise at all was required, after all. While a manager with no understanding of the underlying problem might call him in to (try to) fix old code he had done (purpetrated), I would never hire or recommend him.
This is another reason to write good, well-documented code. It can get you new jobs. If your team was hiring and you had previously worked with someone who wrote really nice code, wouldn't you want to bring that person in?
> If all the code is perfectly documented/written, why do > you think your employer would pay you big bucks? > Unmaintainable code is a gift from God for all the > programmers ;). You might think differently if you're an > employer.
Do you not think that if software where better constructed in a shorter timespan that:
1. There would be more time to make it do what the customer really wants, fix bugs etc and it would be less expensive to do so. 2. If software where built better it may also become cheaper. I don't think this means there would be less work for developers. Making software which is better fit for purpose, easier to change, has less bugs and is delivered to more predictable timescales would encourage investment in new software products and lead software technology into more areas of leasure and business. Microprocessors for example get faster and in effect cheaper - this had lead to the inclusion of microprocessors in thousands of white goods, cars, more powerful cellphones i.e. lots of new market for software.
Matt and Paul, Thanks for your comments. Read my own post again, it seems I was trying to justify or advocate writing unmaintainable code. I was being cynical, but obviously my words caused confusion. Sorry about that. I spend about 70% of my office hours fixing bugs for a legacy system. From time to time, I got really frustrated reading virtually unreadable code. "Job Security" theory is something I use to comfort myself ;) Instead of hating the programmers I've never met and probably will never meet, I thank them for giving me the job. Back to the topic, I don't think the quality of document is the major issue. For me, the problem is the quality of the code. If the code is poorly written, the document doesn't help much. If the code is readable, the document is not that important anyway. So instead of documenting unreadable code, write readable code in the first place. As somebody (sorry, don't remember the name here) says, "An idiot can write code that computer understands; it takes a good programmer to write code that human beings understand."
Posts: 20
Nickname: johnnyo
Registered: Oct, 2002
Re: Why is Poorly Documented Code the Industry Standard?
Poorly documented code is rampant because of widespread geek cultural prejudices favoring code over prose: "Code is sexy, superior and exact, while prose is boring, verbose, and inexact." I disagree strongly with this view.
I concur with a previous poster that documenting code will improve it. I just spent a week reviewing about 85 classes. I initially thought that "Well, this should just be tidying things up, I won't have to actually do any refactoring." Wrong! The refactorings were not large, but they were a clear improvement.
I also second the opinion that "The code is its own documentation" is more or less out to lunch, since it makes no distinction between what service is supposed to be provided and how it purports to provide it.
As far as prose being inexact - poppycock. Example: about one half of the Java Language Specification is written in prose, and I doubt if it could be accused of nebulosity. So it all depends on how it is used. The more I code I write, the more I see the parallels between code and good technical writing : both need clarity and simplicity.
The best way to make a progammer comment his code, is to make him live with the code he writes. And one way to do that is to require that he develop an API.
If that API encapsulates some useful piece of functionality, no one should care how the code works, as long as it works, and is usable. Documenting public methods then becomes critical, otherwise the API will forever remain useless. Writing tests for those public methods also becomes critical, otherwise the project will be a long-term finger-pointing excerise: When something doesn't work, users of the API will blame the developer, and the developer will blame the API's users. He will likely write unit tests in self-defense.
If you make the developer responsible for maintaining that code, there will likely be a lot of documentation over time - or the developer won't be around much longer, since he won't be able to maintain his code (unless that code is trivial).
One of the ways we can enforce proper comments is to check for things other than compile errors in the build process. There are some ant tasks available that check the code for proper formatting, comments, etc. The build should not happen if the code is not properly commented. If we follow the philosophy of daily build then it might ensure that developers comment all their code. However this will only ensure that code is commented. It may not ensure that code is "properly commented" . I have often seen code which was commented in the early stages. Howver the code went through several steps of evolution, but the comments did not. Misleading comments are even worse than not having any comments. Only self discipline can ensure that the comments are always consistent with the code.
> I also second the opinion that "The code is its own > documentation" is more or less out to lunch, since it > makes no distinction between what service is supposed to > be provided and how it purports to provide it.
I strongly believe that a lot of the problem is that people don't understand what comments are for and how they relate to the code - by that I mean how their purpose differs. If someone doesn't understand these things then I can certainly start to understand why they think that the code is its own documentation etc.
Refering back to my previous mail - which detailed two examples of developers who 'had issues' with comments: both misunderstood comments and commenting, their motivation for commenting was simply because someone had told them to so.
The student wrote a comment on every line because he'd heard that an attribute of 'good' code is that it is well commented - so wanting to get a good grade for his assignment he commented every line - even where he couldn't think of a good comment because it was obvious from the code. He was clearly just writing prose which described the line of code. The code was certainly more efficient and exact in this case. However, simply describing a line of code is not the proper use of a comment. In my mind a comment should complement the code, describe a section's purpose and possible side effects + set the context of the piece of code in the overall design.
The colleague of mine who often didn't write comments, only wrote comments because he was told to - he too had been told both at University (in his case Cambridge UK) and by more senior collegues (including me) that comments were an important attribute of good code. When he found that writing comments conflicted with his timescales he stopped.
A failing of his degree and on my part as a mentor is that we'd both failed to teach him what a good comment was and give a clear understanding of commenting to motivate him to do so.
He wanted/wants to be a good developer, he isn't lazy - he just didn't understand what a good comment was or why it was important. Some of us grow to realise what a good comment is and what makes it so, and hence why they are important. Other will eventually, while others will probably never - unless someone teaches them.
There are several types of documentation and bad documentation is too broad a definition. Documentation can be plotted onto a graph where one axis is completeness which ranges from complete through incomplete and all the way down to absent with a second axis of correctness which ranges from perfect through incorrect (to varying degrees) to complete BS.
Good documentation ranks thus; 1 - complete and perfect - This is what we want, maintenance will be swift and painless 2 - absent - This is the next best thing, maintenance will be slow but successfull 3 - all the rest - The worst of all possible worlds, we read the documentation which is either incomplete or incorrect and our code will not work untill we ignore the documentation and read the code.
In the event of having to deal with catagory 3 documentation you have two choices. Rewrite it into catagory 1 or simply delete it. I favour the later because no one maintains the documentation and so catagory 1 becomes catagory 3 the moment the code is touched.
A programmers priorities are coding, coding and coding and until they become testing, documenting and coding, in that order, all these sorts of issues will haunt us.
Why isn't good documentation the norm? Programmers aren't rewarded for it.
Why aren't they rewarded for it? Their bosses are poor businessmen. Typically the boss is a promoted programmer who has essentially zero experience running a business. To be sure, the boss isn't rewarded for producing quality software either. Its a circular loop.
I'm always amused at how pathetic programming efforts look when comparing the attention of detail between us and say a military force or the Detroit Red Wings as they prepare for another Stanley Cup run. Face it, most people don't want to pay the price to win.
Once success is properly envisioned and folks are truely motivated (with the Benjamin's - as nothing else seems to work), then excitement and progress abounds. This is exactly what high-buck execs are paid to do.
Flat View: This topic has 20 replies
on 2 pages
[
12
|
»
]
Previous Topic
