Complete Software Engineering: Picture this

Picture this

November 19, 2004 at 06:55 AM
by rgrzywinski | 4 Comments

It has been said that a picture is worth a thousand words. Developers have been left with out this benefit since the dawn of the computer age.

In more recent additions to the plethera of available programming languages, such as Java and C#, developers have been able to use HTML or HTML-like contructs to add references to images to the source code. In order to see the images, a developer must pass the source code through a translator which outputs HTML. This HTML is then brought up in a browser where the images are finally seen. There are quite a few steps to go through just to reap the benefits of having images available and obviously this process isn't WYSIWYG.

What a developer actually needs is to be able to see the images in her editor along with the source code. A first pass implentation of this can be done today without changing the source code storage format in any way.

Text editor with images

Javadoc with Images

But why stop there? Why show HTML and javadoc tags for other elements? The entire javadoc can be shown and edited WYSIWYG in the source code editor.

Text editor with WYSIWYG

WYSIWYG Javadoc in Source Editor

The concept can be extended even further to all comments to provide for an incredibly rich development environment. The image below shows what an inline-WYSIWYG editor might look like. This editor may be rich enough to create and manipulate the shapes seen in the image. The format in which the source is saved would need to be enhanced to store this rich media information.

WYSIWYG Comments

WYSIWYG Inline Comment in Source Editor

This entry is continuing the thread on separating the presentation (view) of a programming language from its storage format (model). There are also entries on annotating, internationalizing and de-textifying source code as well as simplifying the understanding of code structure.

Read about Code Views.

Comments

Comment by bluedoze at November 20, 2004 04:42 AM

This is a nice idea, but what will happen when you try to open the source code in a smiple text editor, this should be considered also.

Comment by rgrzywinski at November 20, 2004 08:49 AM

I'm going to give away the punch line a little bit here, but I'll explain by way of an anology. If you're working in Microsoft Word or Excel or any other content editor, do you expect to go into the .doc or .xls file with a text editor?

I pose this question to you: why is it that developers need, want, or desire to circumvent a content editor and edit the storage format directly?

My current thoughts are:
o It's always been done that way.
o Since the presentation format and the storage format are identical, doing one implies that you're doing the other.

Thanks for the comment and please keep them coming!

Comment by Dan at July 18, 2006 10:11 AM

An excellent idea.

No need to be so revolutionary about the format! JavaDoc allows for HTML (including images - which I would love to see proper editor support for). This already allows for a much richer documentation than is generally used.

Then extend to also support SVG tags in the same way? I.e. allow JavaDoc to contain HTML and SVG tags.

But I would always want to be able to edit code directly as plain text.

Firstly, when integrating code (e.g. using CVS or SubVersion), you need to be able to view and edit diffs between files. Which is straightforward with plain text, and much harder with a WYSIWYG.

A fancy content-editor is never 100% reliable. My experience with WYSIWYGs is that a good one will do what you want 99% of the time. But there are always times when they get stuck.

With a document, you eventually find a way of making the document appear as you want it. Underneath the underlying data has probably got quite mangled, but as long as things look fine, then that's OK.

For code however, you want to be able to get at the underlying format and make sure it's right.

Comment by rgrzywinski at July 19, 2006 07:31 AM

"No need to be so revolutionary about the format! JavaDoc allows for HTML"

This is exactly what I propose. Rather than editing the JavaDoc / HTML document directly you should be in a WYSIWYG editor editing the content. As for Java code (or any code for that matter) I would suggest a structured language (such as XML) for the document. What's nice about XML is that if JavaDoc was tighted up slightly (i.e. made XML itself) then you could use XML namespaces and it would all be one happy document.

Thanks for the comment!