This exactly. If you expect programmers to read and edit code under a particular kind of interface, such as text with a particular kind of syntax highlighting, it would make sense to judge readability in terms of that interface.

Anyway, the two-comment idea seems to happen for me already! I always write "NOTE:" or "TODO:" when my comment isn't just a narrative explanation or other straightforward hand-holding. In Java and JavaScript, TODO (if not NOTE) is commonly highlighted in a more prominent color.

Even without highlighting, I think it helps that my "NOTE:" and "TODO:" labels are in capital letters. :)

While the idea may exist in practice (at least for me), that doesn't mean the language can't take it further. IDEs with code folding support tend to support folding of comments too. A language with long-form and short-form comment syntaxes might provide an option to toggle all long-form comments within a single block of code, while leaving the short-form comments alone. (This might just make it easier for people to forget to keep the comments up to date, but maybe code edits could trigger a red highlight around the comments as a reminder.)

---

"Are there still other uses for [comments]?"

The uselessness of comments often makes them useful, in a self-defeating cycle. :-p http://c2.com/cgi/wiki?HotComments But I guess we're focused on different ways comments can be used for documentation.

Javadoc, Docco, and inweb handle HTML, Markdown, and TeX in comments. Unlike syntax highlighting, these tools have a compile step (and may erase details that are visible during maintenance), so there can be a struggle between readability at the maintenance side and readability at the publication side. Last time I used JsDoc, I think I wrote at least one comment describing how the formatting worked for another comment.

The code for Docco, as rendered by Docco: http://jashkenas.github.com/docco/

The code for inweb, as rendered by inweb: http://inform7.com/sources/src/inweb/Woven/index.html

Mathematica goes to the trouble to provide rich visual notation for code itself, but it doesn't appear to innovate in the realm of rich WYSIWYG comment formatting. It just has monospaced inline comments and the ability to render "text cells" of explicit markup:

http://reference.wolfram.com/mathematica/tutorial/Documentat...

http://reference.wolfram.com/mathematica/tutorial/TheStructu...

Meanwhile, Inform 7 code is enough like English that it might as well be edited in a word processor. A language IDE could potentially start with the comprehensive text-managing complexity of a word processor, and then add code-specific functionality like error highlighting, autocompletion, and interactive visualizations.

For me personally, I normally never write comments. When I do, it's only for three reasons:

---

1) To provide a reminder for things that need to be fixed later. These always contain "TODO" at the front, like this:

  // TODO: replace foo with bar

---

2) If I'm writing a library that I expect other people to use/modify/whatever, I'll comment anything that I consider to be really important for using the library.

For instance, in the Pratt parser that I wrote last night (in JavaScript), I used comments like this:

  // Converts any array-like object into an iterator
  // <n.expression>, <n.parse>, and <n.parse1> all expect an iterator

  // Expects an iterator of tokens and an optional priority
  // Parses tokens until it finds one whose priority is lower than or equal to <i>
  // Returns the parsed expression

  // Expects an iterator of tokens
  // Returns a list of all the parsed expressions in the iterator

  // Creates a token that throws an error when used
  // This is useful for placeholder tokens, like the ending pair of braces

  // Creates tokens for braces
  // Example usage:
  //
  //   var t = new PARSE.Tokens()
  //   t.braces("(", ")")
  //   t.braces("[", "]")
  //   t.braces("{", "}")
  //

And I especially tried to only give examples of usage when necessary, because examples take up a lot of space. So my commenting philosophy seems to lean toward "don't comment unless it's important, and try to keep comments as short as you can".

---

3) If I'm writing internal code that only I use, I'll very rarely put in a comment that explains something tricky:

  // This is needed because of foobarqux

Because most of the code I write is in Arc/Racket and is for my own use, the only comments I write are of type #1, and very rarely type #3.

---

If I were to use comments I think I would agree with having very few and making them fairly silent. Personally, though, I've abandoned comments all together. Aside from the fact that comments can easily become stale, old and even misleading, I do believe any effort put in to commenting is better spent making the code more readable or even creating unit tests as a means of telling the actual story.

I've been experimenting with two kinds of highlighting for comments: http://i.imgur.com/H1h7M.png (http://github.com/akkartik/wart/commit/b922700733#diff-17). The 'landmark' comments are in the lighter blue (cyan). They're often section headings, but not always. Notice how I highlight the parts of the repl, and connect up the parts of the read stage with later phases. This might help highlight the one key line in a large main function that leads to the true skeleton of the program.