Would rich-text help comment code? [closed]

Question

I always wondered why I have to write rich-text code comments a.k.a. pseudo code in a text editor (c'mon, bold, underline!) and come back to the IDE (integrated?) to write the actual program, not to mention ensuring these documents stay near the code.

So the question is, What if IDEs allowed rich-text code comments. Would it help anyone? Maybe make the murky picture clearer to understand considering you can emphasize or stress on important points and use headers and sub-headers?

(yeah, I know we can manage with *important point* and ****** HEADER ****** but lets think out-of-the-box for a moment!

I'm talking about an RTF Code Editor, integrated within IDEs.

Answer 1

This is an interesting question, because aside from whether it is actually a good idea right now, it pushes the boundaries of the way we work.

All of the reasons for not mixing rich text and code do not address of the question of whether this would help anyone - whether there is also an up-side that compensates for the disadvantages. Perhaps we would all still be using gopher if no-one had asked this kind of question and invented the web.

As for source code comments, some rich-text features would be more useful than others:

• hyperlinks would certainly be useful since code documentation frequently needs to refer to documentation that lives outside the code, as well as links to documentation elsewhere in the code to avoid duplication
• images would be useful because there are many cases when the most sensible code documentation is a diagram - some people do use UML, for example
• lists would be useful - this list, for example, is easier to read in its rich text version (i.e. the HTML) than the Markdown source
• font-formatting is less important - bold and italics are occasionally useful for emphasis and text is more readable if code fragments (e.g. a variableName) are easier to read when formatted differently; different colours make little sense
• headings would not usually be useful, because if a code comment is so long that it needs headings to introduce structure, it should probably be outside the code.

Ironically, it is harder to argue against rich text comments in code, when you are posting rich text comments on Stack Overflow - you have to resort to the argument that rich text is okay 'sometimes'.

Even in short comments here, rich text turns out to be useful, and the Markdown source remains sensible when you do not see the formatted version. So perhaps a good compromise would be for an IDE to render Markdown comment blocks as rich text, and show the Markdown source as soon as the cursor position is in the comment block.

Answer 2

Generally, the idea of commenting your code is to explain what action your individual routines (or the component parts) are intended to achieve. You shouldn't need to be marking those comments up with extra formatting and what others might consider clutter.

If a particular section needs images, emphasis or in some other way needs a deeper explanation then that demonstrates a need for Release Notes or supporting documentation. A developer's nemesis, I know, but it's better to keep things tidy and easily-supported.

Answer 3

The problem Steve McConell cites for complexly formatted comments is that, since they are more work to change, they are more likely to go stale.

One might be able to get around this problem IF an entire team adopted a rich-text editing IDE. But you would embarking on a brave, new code creation methodology, something that most teams wisely tend to avoid in favor of adapting current best practices.

Actual embedded documentation is another question and I am not sure the best way to deal with this.