4 ms·

Comments - like documentation - are a liability. Most projects tend to treat them as supporting artifacts, but they are actually unidentified risks. Did you acc

by swanson 14y ago

Comments - like documentation - are a liability. Most projects tend to treat them as supporting artifacts, but they are actually unidentified risks. Did you account for the time spent either rewriting documentation/doxygen/comments as you go (frequent chunks of small work) or an after the fact round of document backfilling (single chunk of large work) in your schedule? No one even reads those documents. The client claims they are to assist future developers - internally or another vendor - but would you trust a Word document or a .cpp file when everything is on fire and you need to figure out a system's behavior? Same thing applies for code comments. There is one source of truth in software, the code. You can pile on the design documents, wikis, and architecture diagrams but at the end of the day, what is coded is what gets executed. Make the code easy to understand and reason about. And then, if you really want to be nice to future developers, throw in a single page overview of the codebase (README) that gives someone an entry point. Edit: I will just add the caveat to preempt the inevitable - this does not apply to public facing documentation of an API/framework/library etc.

seanmcdirmid 14y ago
This. Comments and documentation are pointless unless they are audited and vetted somehow, then there is the extra cost associated with maintaining them. Managers who don't know better think its just a bit of extra work that the developer does up front, but that is pointless without the above.
leothekim 14y ago
"There is one source of truth in software, the code." I agree with this statement wholeheartedly. Documentation starts with readable code. Comments can go out of date and, worse, lie to you.
- cobrausn 14y ago
  Not all code is readable. Some of it always ends up being an ugly hack. If that ugly hack is not documented, I want to start punching previous developers. I wish people would stop taking these purist approaches. There is an obvious middle ground to this - document the non-obvious and your public facing APIs.
  - sethetter 14y ago
    Perfect. There's always going to be an edge case, and with code there is always going to be some logic that can't be understood at first glance. Tests are great, but comments help too. As long as comments stay updated with code changes they are useful.
- scaryclam 14y ago
  Comments can indeed lie to you, but code can also be doing something that was not actually intended. Having a comment to clarify intent is a saving grace when code looks correct but is doing the wrong thing. At least when a comment is conflicting with the code you know at once that you need to start asking questions...
wulczer 14y ago
> Comments - like documentation - are a liability. Tests, too. But you wouldn't advocate not having tests, right?
- seanmcdirmid 14y ago
  Tests that are executed automatically as regression are fine. There is now way to regress with comments. Tl;dr not equivalent.
  - plorkyeran 14y ago
    This is one of the reasons why I'm a fan of doctests in python. Generally if the tests start to fail the documentation surrounding it needs to be updated as well, which makes it a bit easier to actually keep the documentation up to date.
- swanson 14y ago
  It all comes down to: does the benefit out way the costs? A well-maintained suite of automated tests provide an enormous benefit. A brittle set of Selenium scripts costs a project more than paying a Tester to manually run scenarios.
  - wulczer 14y ago
    Yeah, I agree, it's a question of cost vs benefit. A bunch of tests that check trivial cases is not helpful at all, a well-maintained suite of tests is very useful. What I mean is that a bunch of documentation that only states the obvious is not helpful at all. A set of well-maintained (!) code comments can make navigating unfamiliar code much, much easier.
- enjo 14y ago
  I can prove that tests don't function. They are exactly the opposite of comments in that way. Change the functionality? Tests fail. I know they fail. I fix them. Yet comments can (and do) go way out of date.
niggler 14y ago
"would you trust a Word document or a .cpp file when everything is on fire and you need to figure out a system's behavior?" There's a bigger philosophical problem here. If your development cycle is code -> comment -> code -> comment ... (where you write code and then comment), then your criticism is fair. But the right way is to comment first. When you describe what you want in words, then you or anyone else can go back and evaluate if the code matches the words. (In my experience, 90% of bugs stem from developers thinking one thing and implementing something different, and these could be avoided if you had a normative document) It's like writing a paper: you outline, sketch out what you want to say, and then actually start crafting sentences. The outline should guide your paper, and if there's a problem you first update the outline.
- swanson 14y ago
  Write a test first -> figure out how you want to interact with the code -> then actually start crafting code. And the test can actually be executed. I used to do the "sketch it out" a lot more, but I think Test-First is a better approach.
  - niggler 14y ago
    Test-first is also broken, because you end up crafting code that suits the test coverage. https://github.com/shtylman/node-int/issues/1#issuecomment-12757935 https://github.com/shtylman/node-int/issues/1#issuecomment-1... is an example of an issue which came from an implementation without 100% test coverage. I claim that unless you know every single way in which a function is used, and even if you did, you can't design tests to cover 100% of use cases.
angersock 14y ago
I couldn't disagree with this more strongly--giving somebody a blob of code (no matter how elegant) is a recipe for disaster. Let's assume good comments--not useless, lying, or broken ones. I won't contest that bad comments are at least as bad as useless, as you doubt would not contest that bad code is at least as bad as useless. When I read a comment, I parse it directly. When I read code, no matter how neat it is, I often trigger a twitch of "How would I rewrite this?", which itself gets in the way of understanding. The more code there is, the harder it is going to be to digest at first glance, and if your codebase could be adequately described by a single page of text I would wonder why I need to work on it instead of rewriting it entirely. Hint: if you only have one page of docs, and especially if you have no test suite, I cannot work on the code in a meaningful way safely. If you don't value safety, if you don't value engineering, then by all means omit comments. It's just a crutch for people who can't see the code man. I might also point out that that same philosophy implies that we should just stick with assembly. Especially if you use any language with dynamic types/duck typing (Ruby, Javascript, etc.) seeing "at a glance" what exactly is the proper form of data to pass into and out of function can be hard. Documentation here helps. EDIT: Note also that commenting in libraries, or in mathematical or geometric routines, can be really helpful. The code doesn't lie, sure, but if you aren't experienced/schooled/clever enough to recognize what is going on it won't help you. A great example of this is the fast inverse square root hack: http://en.wikipedia.org/wiki/Fast_inverse_square_root http://en.wikipedia.org/wiki/Fast_inverse_square_root This has great examples of both inscrutable (but honest and short!) code, and shitty commenting.
- dman 14y ago
  The problem domain of the source code dictates the value of the comments. If the code is highly algorithmic or data structure driven its more useful to include a pointer to a book / paper rather than littering the code with comments which will never do as good a job at exposition as a book / paper. On the other hand arcane business logic needs to be documented because there is no way to recreate that from a mental model.
  - angersock 14y ago
    Generally I would agree with this--the problem is that citing papers/books/sites can result in brittle, broken external references. Ideally both a brief explanation and a link to the source material would be helpful.

by swanson 14y ago

seanmcdirmid 14y ago

This. Comments and documentation are pointless unless they are audited and vetted somehow, then there is the extra cost associated with maintaining them. Managers who don't know better think its just a bit of extra work that the developer does up front, but that is pointless without the above.

leothekim 14y ago

"There is one source of truth in software, the code." I agree with this statement wholeheartedly. Documentation starts with readable code. Comments can go out of date and, worse, lie to you.

cobrausn 14y ago
Not all code is readable. Some of it always ends up being an ugly hack. If that ugly hack is not documented, I want to start punching previous developers. I wish people would stop taking these purist approaches. There is an obvious middle ground to this - document the non-obvious and your public facing APIs.
- sethetter 14y ago
  Perfect. There's always going to be an edge case, and with code there is always going to be some logic that can't be understood at first glance. Tests are great, but comments help too. As long as comments stay updated with code changes they are useful.
scaryclam 14y ago
Comments can indeed lie to you, but code can also be doing something that was not actually intended. Having a comment to clarify intent is a saving grace when code looks correct but is doing the wrong thing. At least when a comment is conflicting with the code you know at once that you need to start asking questions...

wulczer 14y ago

> Comments - like documentation - are a liability. Tests, too. But you wouldn't advocate not having tests, right?

seanmcdirmid 14y ago
Tests that are executed automatically as regression are fine. There is now way to regress with comments. Tl;dr not equivalent.
- plorkyeran 14y ago
  This is one of the reasons why I'm a fan of doctests in python. Generally if the tests start to fail the documentation surrounding it needs to be updated as well, which makes it a bit easier to actually keep the documentation up to date.
swanson 14y ago
It all comes down to: does the benefit out way the costs? A well-maintained suite of automated tests provide an enormous benefit. A brittle set of Selenium scripts costs a project more than paying a Tester to manually run scenarios.
- wulczer 14y ago
  Yeah, I agree, it's a question of cost vs benefit. A bunch of tests that check trivial cases is not helpful at all, a well-maintained suite of tests is very useful. What I mean is that a bunch of documentation that only states the obvious is not helpful at all. A set of well-maintained (!) code comments can make navigating unfamiliar code much, much easier.
enjo 14y ago
I can prove that tests don't function. They are exactly the opposite of comments in that way. Change the functionality? Tests fail. I know they fail. I fix them. Yet comments can (and do) go way out of date.

niggler 14y ago

"would you trust a Word document or a .cpp file when everything is on fire and you need to figure out a system's behavior?" There's a bigger philosophical problem here. If your development cycle is code -> comment -> code -> comment ... (where you write code and then comment), then your criticism is fair. But the right way is to comment first. When you describe what you want in words, then you or anyone else can go back and evaluate if the code matches the words. (In my experience, 90% of bugs stem from developers thinking one thing and implementing something different, and these could be avoided if you had a normative document) It's like writing a paper: you outline, sketch out what you want to say, and then actually start crafting sentences. The outline should guide your paper, and if there's a problem you first update the outline.

swanson 14y ago
Write a test first -> figure out how you want to interact with the code -> then actually start crafting code. And the test can actually be executed. I used to do the "sketch it out" a lot more, but I think Test-First is a better approach.
- niggler 14y ago
  Test-first is also broken, because you end up crafting code that suits the test coverage. https://github.com/shtylman/node-int/issues/1#issuecomment-12757935 https://github.com/shtylman/node-int/issues/1#issuecomment-1... is an example of an issue which came from an implementation without 100% test coverage. I claim that unless you know every single way in which a function is used, and even if you did, you can't design tests to cover 100% of use cases.

angersock 14y ago

I couldn't disagree with this more strongly--giving somebody a blob of code (no matter how elegant) is a recipe for disaster. Let's assume good comments--not useless, lying, or broken ones. I won't contest that bad comments are at least as bad as useless, as you doubt would not contest that bad code is at least as bad as useless. When I read a comment, I parse it directly. When I read code, no matter how neat it is, I often trigger a twitch of "How would I rewrite this?", which itself gets in the way of understanding. The more code there is, the harder it is going to be to digest at first glance, and if your codebase could be adequately described by a single page of text I would wonder why I need to work on it instead of rewriting it entirely. Hint: if you only have one page of docs, and especially if you have no test suite, I cannot work on the code in a meaningful way safely. If you don't value safety, if you don't value engineering, then by all means omit comments. It's just a crutch for people who can't see the code man. I might also point out that that same philosophy implies that we should just stick with assembly. Especially if you use any language with dynamic types/duck typing (Ruby, Javascript, etc.) seeing "at a glance" what exactly is the proper form of data to pass into and out of function can be hard. Documentation here helps. EDIT: Note also that commenting in libraries, or in mathematical or geometric routines, can be really helpful. The code doesn't lie, sure, but if you aren't experienced/schooled/clever enough to recognize what is going on it won't help you. A great example of this is the fast inverse square root hack: http://en.wikipedia.org/wiki/Fast_inverse_square_root http://en.wikipedia.org/wiki/Fast_inverse_square_root This has great examples of both inscrutable (but honest and short!) code, and shitty commenting.

dman 14y ago
The problem domain of the source code dictates the value of the comments. If the code is highly algorithmic or data structure driven its more useful to include a pointer to a book / paper rather than littering the code with comments which will never do as good a job at exposition as a book / paper. On the other hand arcane business logic needs to be documented because there is no way to recreate that from a mental model.
- angersock 14y ago
  Generally I would agree with this--the problem is that citing papers/books/sites can result in brittle, broken external references. Ideally both a brief explanation and a link to the source material would be helpful.