Separate code and comments

Question

I'm finding comments on code starting to get annoying. I feel that once you achieve some level of expertise, code is pretty much self documenting. But comments are still a necessity. What I would like to know if there's such a plugin or IDE with this idea of comments separated from the code. If such a thing doesn't exists, what ideas do you think would work great on a plugin for an IDE like Eclipse?

Take this Python code for example:

def do_something(self, var):
    # * 541
    ...

Then some XML like this:

<comments>
 <comment id="541" file="x.py" line="14">This is a comment</comment>
<comments>

Thanks!

Answer 1

Donald Knuth explored this topic heavily under the title of "literate programming" (which is a fine starting point for Googling). He wrote a program called Weave (or was it Web?) and Tangle which does something like what you ask, but for Pascal code.

I'm afraid the idea never got very far off the ground and I've never heard of anything similar for Python.

These days, there's a community of programmers who believe in writing short methods with names and variable names sufficiently descriptive to make comments (usually) unnecessary. The rest of us just plod along and comment the way we've always done.

UPDATE

I lied! There's something called PyLit, here: http://pylit.berlios.de/literate-programming/index.html . Also, a pretty extensive discussion of the whole thing.

Answer 2

Good comments add information, such as why, they don't repeat code, so I don't agree with the premise of the question.

However, to go along with the idea for a moment, I can imagine an IDE that hides comments while you are editing, but storing them separately is a recipe for confusion.

Answer 3

Don't forget that good comments explain intent and consequences, not literally what the code is doing.

Having said that, have you looked at code folding within IDEs ? Eclipse (for one) will collapse comments and hide them. You can reveal them at the press of a button. The comments remain in the code and tied to the relevant sections without any indirection (as you're proposing) so you can view them in any editor/environment.

Answer 4

I've never heard of such a thing as externalized comments, and I think they'd be slow or easily corrupted, because they'd always have to be updated to stay in sync with the code. Furthermore, if your idea is to completely eliminate them from your view while you're working on your code, you could forget to update them and they could become inaccurate.

A feature you should look into is code folding. Instead of separating the comments into a different file, they're collapsed into a smaller space when you don't want to look at them. Many IDEs implement it (eclipse is one).

Answer 5

A quick fix that will work with most editors is to change the syntax highlighting colour scheme to make the comments invisible or barely visible, e.g. light grey text on white background.

If your editor supports multiple colour schemes then you could have one that hides the comments and one that hides everything except comments, then swap between them.