What is less annoying: no source code documentation or bad code documentation?

Question

Hello everybody!

Today I had an argument with a colleague about one of his comments as summary of a method. Mostly he is not writing any summaries but in this case he added one and it was a really bad one: It was not described what the method is doing, it assumed what the method maybe is doing. I have to add that this piece of code was not his own, it was legacy code.

I told him that in this case he should have never made any commentary, only after really checking what is happening there, because someone who does read his opinion as valid statement will not check by himself and screw up. He could have add "This is an assumption, please check for yourself." but he didn't. Even if no commentary was there it would be better because then the developer has to check for himself.

Personally I'm very strict on code documentation. That doesn't mean I comment every line of code but method, class, etc summaries are mandatory and additional lines for difficult code parts are helping too.

I have to add that I work in a team of 10 developers where no one writes code only for himself. Spending less time on code documentation means that other developers are spending more time to get the meaning of the code.

I'm not even able to say if I like no documentation less than this kind of bad documentation. But at the end I guess I spend more time with not documented than not good documented foreign code. So... I hate both. ;)

What do you think? You don't care or do you see these things in your daily work too? What is worse for you: no code documentation or bad code documentation?

Thanks!

Michael

Answer 1

No documentation is far better. I would rather have to understand it myself than be mislead by incorrect guidance.

Answer 2

If i would have to choose, i would rather have bad code documentation. Since bad source documentation can spell horror for confusing code later on, making additions to the code close to impossible.

Answer 3

Incorrect documentation that looks authoritative is worse than no documentation.

Incomplete documentation is better than no documentation.

Speculative documentation that is marked as such is, often, better than no documentation.

Answer 4

I find the quality of the code has considerably more bearing on my ability to work on it than the quality of the documentation.

I've working on code that was almost entirely undocumented (with comments appearing only occasionally), but was still perfectly understandable. I've also worked on code that has reams of docs and virtually every line commented, but verging on impossible to work on.

Bad documentation is certainly extremely annoying, but worse is code that is so convoluted and badly-designed that you need to grope though pages and pages of docs to do anything.

Answer 5

No documentation is better. I've been bitten by misleading documentation and have resigned myself to being cynical about what it claims. In most cases its usually what the developer wanted to do rather than what it does actually (especially in the absence of test :/)

Answer 6

Bad documentation is worse. Bad documentation often lies (unintentionally or otherwise), which can lead you down the wrong path from the start. Bad docs can keep you from realizing your mistake because you think you're in the wrong when something doesn't work, when really it was never meant to be. Bad docs can also affect your perception of overall product quality, since you can't be sure if the behavior you're seeing is incorrect documentation or an actual bug in the code.

I'd rather have good docs of course, but given the choice between bad docs and just working slowly through the source code, I'll take the source option.

Answer 7

Wrong documentation is worse than no documentation.

Answer 8

"Documentation is like sex; when it's good, it's very, very good, and when it's bad, it's better than nothing. (Dick Brandon)"

No seriously, you have a problem when the documentation is plain wrong. If it's just bad (because it's vague or incomplete for example), you can at least be glad it's there. You notice this very quickly when working with some completely undocumented APIs. MSDN is full of those, where the documentation is incomplete and vague - but it's still so much better than none at all.

Answer 9

One problem with anything other than complete or no documentation is that you may mistake incorrect or incomplete documentation for complete, accurate documentation, and poor documentation can lead to none (why document code? all his comments are wrong anyway).

I would prefer no documentation to bad documentation.

Answer 10

hmm.. the question to ask yourself is: is the bad documentation bad, or is it that it is correct and the code is wrong?

eg, the summary says "this routine does xyz", but the code actually does abc in a strange way. If can often be that the summary is right - that's what the code should be doing, but the author was a complete nincompoop.

I've seen this most often when it comes to return codes, the summary gives a good set of codes that should be returned, but the routine returns 0 everytime.

In any case, its a bug and should be fixed or at least marked with a comment. 'Bad' documentation that gets updated, even with just 'WTF?' marks, is better than no documentation. Documentation that looks stale just doesn't get read.

One last thing: choosing "Bad documentation" is certainly better than officially not writing documentation because it might get bad later. Programmers are always finding excuses not to write comments :-)

Answer 11

Bad documentation is often on worse code, I'd say bad documentation on good code might be a problem, but how often do you see that?.

If it's an assist from someone who has worked their way through the code before, it can give you a heads up.

If it's from the original author, maybe it can offer some insight to his twisted mindset, perhaps it can be the key to unraveling a mess--or give you a heads-up that some code you are about to refactor is tricker than you'd think at first glance.

I see a lot of people saying bad documentation is worse, but can't come up with a single scenario (and I've never seen one) where it was actually worse.

Usually you hear anti-documentation cries from people who don't really understand what their own code does and can't, therefore, properly comment it. (IE:, they are the authors of the bad code/comment scenario currently under discussion)

Answer 12

Bad documentation is worse than no documentation. However, I would argue that, as far as possible, your code should be self-documenting. i.e. you should choose meaningful names for the entities in your code, and have short methods. Comments explaining what the code is doing should then be virtually redundant, because it is clear from the code itself. Comments would mostly be used to explain WHY your code is doing something.

Answer 13

No documentation is far better.

In fact, I am willing to go one step further. Keep documentation at a high level, and don't document too many details.

Once you have a decent understanding of the high level structure, no documentation is better than understanding the code, by reading the code.

I don't trust anyone working on a module who does not understand what that module's code is actually doing. If you want to use the module as a black box, fine, read the doc. If you want to change its behavior, almost better to not give you documentation and have you figure out what it does in all the cases.

Answer 14

If developers (i.e. users of the APIs) have access the source code, then bad documentation is worse than no documentation. But at least once the users have figured out that the documentation is bad, they can look at the source code to find out the answers to their problems.

If developers don't have source code access, then bad documentation may be better than no documentation, depending on how simple the APIs really are to use and how bad the documentation is. If the documentation is really bad and source code is unavailable, the user may need to give up on using the APIs entirely.

Answer 15

Code documentation is important but its completely insignificant compared to Unit/Acceptance/Functional Tests. (When I say code doc I'm taking about per method/class doc not high level design/api doc).

What your colleague should have done was wrote a bunch of tests to back his assumption and then changed the doc.

Answer 16

This is obviously stepping into subjective territory, but based on my definition of bad documentation, it's far worse than no documentation!

To help define that more clearly, I once had a co-worker who wrote the worst kind of documentation possible. She focused only on implementations and never wrote documentation in the headers (where the public interfaces are defined).

She wasn't lazy at all. With every implementation source file, she wrote a manual (described as such with a table of contents and everything). Each one was at least a dozen pages, and sometimes as long as 30 pages. This manual was almost entirely about how the code was implemented and was often even longer than the code itself (it'd generally take less time to read and understand the code than the manual). It was also downright boring, describing details that would generally be self-evident like how variables are being used, etc.

The problem with documentation that so strongly emphasizes implementation details is that implementation details change (interfaces not so much). The result is that a lot of implementations got changed but these manuals weren't updated. It wasn't long before the manuals were incorrect and misleading and lead developers to make incorrect assumptions. With these mistaken assumptions came a lot of subtle bugs.

Had there been no documentation at all, there may have been mistaken assumptions and bugs as a result, but at least those mistakes wouldn't have come from the documentation itself. I also learned just how much more important it is to focus on interfaces first and foremost for documentation, as implementations really do tend to change over time. If the interface is documented appropriately, the implementations can generally be understood by someone with the right expertise and even replaced completely if the interface is comprehensible, but documentation that just focuses on implementation tends to get out of date quite quickly.

Answer 17

IF you have a good code then you don't need any documentation at all. "GoodCode" I mean that each function has a self-explanatory name, function purpose is clear, etc...

The only thing is required to be commented is VERY OPTIMIZED methods those readability sacrificed for the purpose of optimization. But that should be not more then 3-5 functions per application: usually only 20% of application causes performance issues (or any other issues). And only optimization of 20% of those 20% (totally 4% of the whole application) could be fruitful to optimize.

The less comments in code - the more readable code is (Refer to Steve McConnel (http://www.stevemcconnell.com/books.htm) and others)