Would rich-text help comment code?

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

Absolutely not! I simply don't trust anyone to be mucking around in my code with "special characters" that may, someday, give me another source of headaches.

Update: Jeremy points out that the comments - including any formatting - would always be stripped out before the file was submitted to the compiler. This is fine but I still viscerally dislike the idea of putting control characters in my code.

One approach that does work is what ReSharper does. When it is "watching" your code, it will bold and turn blue any comments that start with "Note:". This is useful because no one is messing with my text format - they are just using color coding based on content.

So again: don't change my file format. But highlighting stuff based on content is fine.

Answer 2

you could check phpdoc format used - basically it uses tags to mark the content, but can contain links etc.

Answer 3

No, because then comments may be unreadable by users who view your code without your special IDE additions.

However, I can understand customizable auto-formatting for your IDE. For example, your IDE could be configured to process comments under Markdown (which StackOverflow uses), which has the benefit of having readable "code."

Answer 4

If you let this idea pass and become popular, one day you will find Excel spreadsheets, or videos, embedded in someone's code. No, please, let source code, at least source code!, be plain old text.

Answer 5

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 6

Javadoc has allowed HTML tags and a bunch of custom tags (eg to link to other classes or methods) for the last decade.

Answer 7

The structure that I want of documentation doesn't match the structure of the source code.

For example, a functional spec is a list of features: each feature is described in one place ... but the implementation of a feature, for example as a transaction from the UI to the database via the DAL, isn't in one place in the source code.

Also, different people want different types of documentation:

• What's the functional spec?
• What's the UI?
• What's the data design?
• What's the software design?
• What's the development project/process?
• What's the test case?
• What's the test result?

Puting documentation in the same source files as the source code doesn't help, imo.

However, see also "literate programming". I don't know what "literate programming" is or was meant to be, but it looks useful in at least one narrow case, which is, when you're trying to write about software (e.g. to write an article about some software).

Answer 8

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.

Answer 9

The only rich text that I really desire in comments is hyperlinks to reference other pieces of code. This is pretty easy to accomplish with Javadoc-style comments, or just with ctags.

If plain text comments aren't clear, you probably need better documentation, not better documentation formatting.

Answer 10

I kind of like the idea. Since comments are already one color, it would probably need to be somewhat limited, not true rich-text, or it would be hard to pick out the comments from the code. But if it only allows bold, underline, and perhaps font size, it would be useful for emphasizing that you know the code is a kludge, or a "don't ever edit this" type of comment.

It wouldn't work until it was part of a common and widely used IDE, however.

Answer 11

Actually, what really helps to comment code is when languages take the most frequently used comment patterns and turn them into language features:

The final keyword can do away with this type of comment:

// Don't extend this class! Ever!

Abstract methods replace this:

// make sure you implement foo() bar() and baz() in all child classes

And good object-oriented programming will organize code so that you don't need big annoying headers:

// *******************************************
// ***** Input Handling here *****************
// *******************************************
// * This next section has all the functions *
// * dealing with keyboard input.            *
// *******************************************

... becomes ...

class InputHandler {
    // This class deals with keyboard input.
}

Answer 12

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 13

i would prefer having only the javadoc rich elements, like , links to classes, headers and such presented in a rich-texty way. this would be converted transparently to javadoc html. i think its a good idea for an ide.

Answer 14

Have a look at the Visual Studio 2010 it has an example extension that inserts images into code files.

Answer 15

It's already possible to put rich text in Python code: sphinx. At least in the form of RST. And it isn't really necessary to use an IDE for it either (although I suppose some formatting help is useful).

Answer 16

Back in the days when NeXT was maintaining their own private branch of GCC, it allowed RTF tags in source code. Not just in comments, but everywhere. It was never a highly-utilized feature, and eventually got dropped. One issue was that RTF is really hard to read with a plain-text editor, so it only worked if everybody on the team used an RTF-aware editor (and diff tool).

I think that retaining some kind of formatting in comments would be potentially useful, but I think something a little more human-readable than RTF might be a better idea. Markdown might work pretty well.