Sunday, 7 September 2008

The Results!

My apologies for taking this long to finish up... but at long last, the results of the Self-Documenting Code Contest are now in. You can see them below.

First things first - although a programming contest judged by a non-programmer sounds good on paper, it turns out to be a nightmare in practise. I think it's hard for us programmers to remember just how far removed programming is from ordinary language.

Initially, Sylvia had trouble even understanding the clearest of the entries. To get meaningful results I had to sit with her, giving hints such as "think of it as a recipe, or a series of instructions", that "print" means producing output, that "string" means a piece of text, and that (in most languages) unlike the familiar mathematical concept, an equals sign does not mean true, timeless equality.

She also noted that the consistency of her scores was pretty low, since as she went through the entries she was learning more and recognizing constructs from previous ones. And finally she also complained that the whole process was really exhausting, like to trying to follow a conversation in a foreign language you barely know.

So given all these problems, we hit on a compromise: Sylvia would only score the best entries, and her results would just be used as a tiebreaker - to separate entries that would otherwise be equal. (There are a lot of these. See below.) So rather than a number out of 10, her scores are in stars, out of 5.

A blog post isn't really the ideal place for giving details of every single entry. So I've put up the detailed results... in the form of a subreddit!

Check out This is a normal subreddit, so I hope to see everyone giving lots of comments and votes here. It'll be particularly interesting to see whether the final reddit-score matches the judges' opinions. (If I'd thought of this idea originally, I would have had the entire contest hosted here, with entrants simply posting their entries themselves. Maybe next time...)

Anyway, each of the 3 main judges gave each entry a score out of 10, for a total score out of 30. Sylvia then gave a score in stars, for separating entries that got the same score. Here are the top-rated entries:

18th: Leonardo, entry 1 [22**]
Equal 16th: Diego Essaya [22***]
Equal 16th: Tom Newton [22***]
15th: Kari Hoijarvi [22****]
14th: Mathias Hallman [23**]
13th: Tim [23****]
12th: John Evans [23*****]
11th: Chris Rebert [24**]
Equal 7th: Kristian Stangeland [24***]
Equal 7th: Fabien Le Lez [24***]
Equal 7th: Apfelmus [24***]
Equal 7th: Thomas Annadale [24***]
6th. Michael Sloan [24****]
5th. Reinout Heeck [25*]
4th. Kieran Elby [25****]

Congratulations to all - the field was pretty tough.
Now, let's take a closer look at the top 3. All of these scored a 9-8-9 from the judges:

3rd. Martin Ankerl, entry 2 [26***]

class String
def letters

query_letters = "documenting".letters
words ='wordlist.txt').downcase.split

candidates = do |word|
(word.letters - query_letters).empty?

candidates.each do |first|
candidates.each do |second|
combined = first + second
puts "#{first} #{second}" if combined.letters == query_letters
An excellent entry in Ruby. Some very clear string interpolation, and the perfect place for a deferred if. However, the line
(word.letters - query_letters).empty?
was too programmery for Sylvia to follow, and she also had trouble with some of the less-clear english - such as downcase.split, and the class String block at the beginning.

2nd. Arnar Birgisson [26****]
from urllib import urlopen

source_word = 'documenting'
wordlist_url = ''

wordlist = urlopen(wordlist_url).read().split('\n')
source_sorted = sorted(source_word)

for word1 in wordlist:
for word2 in wordlist:

if word2 < word1:

combination_sorted = sorted(word1 + word2)

if combination_sorted == source_sorted:
print word1, word2
print word2, word1
Another excellent entry, this time in Python. The logic really is self-explanatory here.

And the winner of the Self-Documenting Code Contest is...

1st. Ian Davis [26*****]
word_to_anagram = "documenting"

def remove_trailing_whitespace(text):
return text.rstrip()

word_list = [ remove_trailing_whitespace(line) for line in file("wordlist.txt") ]

for first_word in word_list:
for second_word in word_list:
if sorted(word_to_anagram) == sorted(first_word + second_word):
print word_to_anagram, "=", first_word, "+", second_word

A very short, and extremely clear entry. No unnecessary work. I was particularly impressed with the line that generated word_list; it's crystal clear what's happening there. The output format is a little more complex than it needs to be, but it's still perfectly obvious what's happening there.

Congratulations, Ian! I think you just won yourself an Internet or two.

Tuesday, 19 August 2008

Closed for new entries

No new entries now.

The judges have started awarding points; expect the results soon.

Tuesday, 12 August 2008

Deadline change

I'm very happy with how well the Self-Documenting Code Contest has been recieved. Lots of people have written to comment on how interesting the challenge was, and we've had 34 programs submitted so far, more than double my original wild guess.

I only have one problem: that 1st of September deadline. I basically picked it arbitrarily, as a nice round number, but now it's really looking a very long way away. The number of submissions have dropped to a trickle now; it seems unlikely that anyone is really going to need that much time to finish. And most important: I want to get onto scoring them! I'm bored!

Sure, I could probably get more coming in if I submitted the contest to more websites, but I don't really see a need to. 34 is plenty. So I've decided to cut things short: you now have until Monday the 18th of August to submit your programs.

If you're still planning to submit an entry: what are you waiting for?

Monday, 4 August 2008

Announcing the Self-Documenting Code Contest

Programs must be written for people to read, and only incidentally for machines to execute.

-- Abelson & Sussman, Structure and Interpretation of Computer Programs

The Obfuscated C contest has always annoyed me.

If programs are for communicating with other programmers, why do we have a contest that encourages such complete perversions of best practises? (Ok, that's really a rhetorical question - I know perfectly well how much fun it can be to put hours of work into one devious, unreadable block of line-noise.)

But then I thought... someone should make another competition. One that encourages the opposite - learning to make
better code. A competition in which points are awarded for code that's simple, easy to read, more straightforward.

And here we are. As of today, Monday the 4th of August 2008, The Self-Documenting Code Contest (SDCC) is now officially open. I will be accepting submissions all month, until Monday the 1st of September.
EDIT: Correction - I will be accepting submissions until Monday the 18th of August.

The rules:

This contest is about self-documenting
code. In other words, your goal is to write a program whose logic is so obvious, it is its own documentation.
You may not use comments in your program. Nor may you emulate comments by using a purely decorative string value, or a paragraph-long identifier, etc.

2) Any language.
You may use any programming language - but you might want to bear in mind that if a judge is familiar with your chosen language, s/he will probably find it easier to read.

Currently the panel consists of 5 judges, coming from a wide range of programming backgrounds - academic, game programming, web programming, etc... and just to mix it up, my wife, who has no programming experience.

The judges have one thing in common: their knowledge of English. So ideally, that's your target: a program that can be understood by anyone who speaks English.

Unrealistic? Perhaps. But those are the rules everyone is working under.

Your objective:
Write a program that generates all two-word anagrams of the string "documenting". Here's a word list you might want to use:

When you're done, send the results to

Good luck!
Laurie Cheers