The problem with the now-you-see-it-now-you-don't approach is that, when you separate the code and the comments, they quickly diverge. The veteran will tinker w

The problem with the now-you-see-it-now-you-don't approach is that, when you separate the code and the comments, they quickly diverge. The veteran will tinker with the code but never touch the comments, because she doesn't see them and doesn't care to see them. Then the comments become worse than useless, because they will actively mislead or confuse the newb who reads and writes them. This is a special case of the general problem with metadata: you can't keep it in sync with the real data. This is what leads, e.g., Ruby programmers to become religious fanatics about DRY. The other problem is that not all comments are equal: some are fluff, some are fluffy-looking but destined to become HTML documentation and are therefore important to keep around, some are terse and vital, some are hints for future refactorings and bug fixes. A system which hides all comments isn't really what I would want; I'd want to hide the fluffy ones and keep the important ones visible. And suddenly you need meta-metadata, and your editor becomes baroque, and your head explodes.