A blogger some time ago posted a challenge to write code that was "self-documenting." In his words, "A competition in which points are awarded for code that's simple, easy to read, more straightforward." The original challenge is here, and the results are here. The task was to write a routine that would determine all possible two-word anagrams given a starting word and a dictionary (word list). More than 30 entries were submitted.

The originator of the contest wrote at its conclusion, "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."

Well, not everyone has forgotten. I submit to you a solution to the challenge written with Revolution, an amazing programming language based on plain English. Please visit his results page and review the top three winners of the contest, then examine the code below. Which wins the readability challenge?

Revolution code:

constant alphabet = "abcdefghijklmnopqrstuvwxyz"
on mouseUp
  put "documenting" into sourceWord
  put url "http://revuser.com/wordlist.txt" into wordList
  repeat for each character c in alphabet
    if c is not in sourceWord then filter wordList without ("*" & c & "*")
  end repeat
  put sortWord(sourceWord) into sourceWord
  repeat for each line firstWord in wordList
    repeat for each line secondWord in wordList
      put firstWord & secondWord into testWord
      if the length of testWord is the length of sourceWord then
        if sortWord(testWord) is sourceWord then 
          put firstWord && secondWord & return after anagramList
        end if
      end if
    end repeat
  end repeat
  put anagramList
end mouseUp
function sortWord theWord
  repeat for each character c in theWord
    put c & return after theSortedWord
  end repeat
  sort theSortedWord
  replace return with empty in theSortedWord
  return theSortedWord
end sortWord

The general idea here is that if you sort the letters in a word alphabetically, the original word and any anagrams formed from it will be exactly the same. The custom sortWord() function accomplishes this re-arranging of letters. In the above example, I first eliminate words that couldn't possibly work in the anagram, because they contain letters that are not in the original word. Then, only to make comparisons on two-word combinations that are the same length as the source word, again for speed. If you don't care about how quickly it runs, the mouseUp code can be simplified as follows:

on mouseUp
  put "documenting" into sourceWord
  put url "http://revuser.com/wordlist.txt" into wordList
  put sortWord(sourceWord) into sourceWord
  repeat for each line firstWord in wordList
    repeat for each line secondWord in wordList
      if sortWord(firstWord & secondWord) is sourceWord then put firstWord && secondWord & return after anagramList
    end repeat
  end repeat

  put anagramList
end mouseUp

Can you imagine the joy of working on a project written in Revolution? If this sounds like the kind of code you wish to read and write, then try a free 30-day fully-functional demo of Revolution, which sells for as little as $49.