Beautiful Code, or rather, Beaut Comments.

My code isn't worth boasting about, but I think I've written some nice comments in my time.

Here's a comment from TimeSnapper that I'm particularly proud of.

It uses an ascii diagram to describe how a bunch of constants relate to the shape of the TimeBar control:

One day, hopefully my best work will be in the code, not just the comments ;-)

(The obvious side thought is -- why can't we embed diagrams and images in the comments of our code? Or at least some kind of textile-style wiki-like markup/markdown? And how much does that thought make you shudder as a potential avenue of IDE abuse?)

'KristofU' on Mon, 26 Nov 2007 10:32:45 GMT, sez:

An ascii art comment image says more than a thousand words of comment.

'Tim S' on Mon, 26 Nov 2007 10:47:16 GMT, sez:

CodeRush for Delphi allowed you to create diagrams and embed them in your code. See the very last image at this link:

http://www.ackerson.us/AckersonSoftware/Dev/CodeRush/plugins/DelphiVI.html

I would expect that DevExpress is planning to implement this for CodeRush for VS.NET at some point in the future.

'Peter' on Mon, 26 Nov 2007 11:03:16 GMT, sez:

Yeah. There's a to be said for ASCII-art in comments. It's a shame I can't show you a few examples of mine here.

Have you heard of "literate code". This is the idea, first put about by Donald Knuth, that the comments should have primacy over the code, rather than the other way round.

Instead of embedding little snippets of commentary in our code, we embed little snippets of code in our commentary. coding == essay writing. That kind of thing.

If it had taken off, we would all be writing stuff like <code language="C#"> ... </code>, but it wasn't meant to be. Nevertheless, there are some beautiful TeX documents out there, with lovely diagrams, that also happen to be source-code listings.

Incidentally, as a Haskell fanboy, I'm obliged to tell you that Haskell has two literate modes built into its syntax. One of them is a TeX mode, and the other is so simple I can demonstrate it here.

> primes = eratosthenes [2..]
> where eratosthenes (prime:rest) =
> prime : eratosthenes $ filter ((0!=) . (`mod` p)) rest
>
> main = print primes

Just save this comment as "primes.lhs", run it in a Haskell interpreter, sit back and look at all the pretty prime numbers.

'Peter' on Mon, 26 Nov 2007 11:04:59 GMT, sez:

Well, it would if the whitespace hadn't been stripped out. Haskell has layout syntax, like Python.

*Grrr*

'Jon Schneider' on Mon, 26 Nov 2007 15:53:46 GMT, sez:

I've had this same thought in the past -- how to include richer resources than plain text / ASCII art in comments in source code?

One potential solution is linking to such resources by providing the URL of the resource in the code comment.
For example:

// For complete details on the protocol being used here, see http://...

Of course, this carries a risk that the page being linked to may go away eventually, especially if is an external/3rd-party website. Also, linked resources might unexpectedly change; they (presumably) aren't under version control like the source code is.

I do agree that ASCII art is a pretty good solution, since it is stored directly with the code in the version control system, avoiding the problem of the diagram becoming out of sync with the code, as can happen when an external resource is referenced.

'engtech' on Mon, 26 Nov 2007 16:23:31 GMT, sez:

You can "embed images" kinda if you use some kind of autodoc software like doxygen or robodoc.

'Rice Crispie' on Mon, 26 Nov 2007 18:11:14 GMT, sez:

Q. And how much does that thought make you shudder as a potential avenue of IDE abuse?
A. A lot

'Jeff Atwood' on Mon, 26 Nov 2007 20:05:55 GMT, sez:

You write code in Visual Basic! For shame, Mr. Bambrick. For shame. I thought you were a "professional" programmer. **








** this is a joke. I am a long time VB programmer myself, only reluctantly writing in C#.

'lb' on Mon, 26 Nov 2007 20:29:28 GMT, sez:

@Jeff:
i use whatever language is handiest. i no longer see the syntax, i just think in IL.

'KristofU' on Thu, 29 Nov 2007 11:30:54 GMT, sez:

Forgot to mention that I make most of my ASCII stuff in http://www.jave.de/

'Andy Brice' on Thu, 29 Nov 2007 19:31:17 GMT, sez:

Couldn't you just have put the URL of a *proper* image. ;0)

'Farmer Jeb' on Thu, 29 Nov 2007 21:15:25 GMT, sez:

Long been a fan of ASCII art in comments particularly for code that does complex and unintuitive user-interface stuff.

'Greg Wilson' on Mon, 10 Dec 2007 11:43:03 GMT, sez:

I've wondered for years why we (developers) build rich editing interfaces like Word (no, don't laugh, you can actually do a lot with it) for other people, but then restrict ourselves to 100% pure 7-bit ASCII in our code. (Oh, wait, you can put umlauts into C source files now...) I'd really like before-and-after pictures of data structures, architecture diagrams, and everything else *in my code*; shouldn't be that hard to do...?
See http://acmqueue.com/modules.php?name=Content&pa=printer_friendly&pid=247&page=1 for more...

name


website (optional)


enter the word:
 

comment (HTML not allowed)

All viewpoints welcome. But the right to delete any post for any reason is reserved. Don't make me do it. Aim for constructiveness. Comments may be republished, emailed to your loved ones or printed and used as toilet paper. Also, I get particularly nasty on comment spam. It's not worth even trying to post comment spam here -- your html is escaped, and your links are given a rel='nofollow'. By attempting to post a comment, you understand that if the comment is considered spam, at my absolute discretion, your IP address may be used as the target of a prolonged distributed denial of service attack. Your electricity might suddenly stop working. Your car tyres will go mysteriously flat. You will suffer permanent hairloss. Your dreams will be filled with terrifying monsters. And in any case I reserve the right to record and publish your IP address.

 

TimeSnapper_{Know thyself!}

TimeSnapper is a life analysis system that stores and plays-back your computer use. It makes timesheet recording a breeze, helps you recover lost work and shows you how to sharpen your act.

 

NimbleText is a Powerful FREE Tool

Use it for:

• extracting data from text
• manipulating text
• generating code

It makes you look awesome. Use it right now! Go on! Hurry! Don't walk, run!