New Adventures in Software


Revisiting the Comments Debate: The Self-Documenting Code Contest

Posted in Haskell, Software Development by Dan on August 5th, 2008


The great commenting debate generated a lot of disagreement, both here and elsewhere, about the value of code comments with respect to writing self-explanatory code.  If you are of the opinion that good code does not need comments, here is your chance to prove it.  Laurie Cheers has created The Self-Documenting Code Contest.  The idea is to solve a given problem using the most understandabe code that you can write.  No comments are allowed.  The problem is to generate all two-word anagrams of the word “documenting”.

Although I’ve clearly stated my opinion in favour of comments, I decided to give it a shot.  I’ve already submitted my Haskell solution and, to be honest, you’d do well to improve on its readability.  I believe that it satisfies all of the requirements using a brilliantly simple algorithm.

I’ve hidden my code in case you want to try for yourself first.  Click “show” to reveal my solution: show

UPDATE: I got disqualified from the contest for “being a smartass” :(

Want more articles like this? Subscribe to the feed.

5 Responses to 'Revisiting the Comments Debate: The Self-Documenting Code Contest'

Subscribe to comments with RSS

  1. sharfah said,

    on August 6th, 2008 at 12:46 am

    Well, you’re not generating them so you can’t call it generateAllTwoWordAnagramsOfTheWordDocumenting! Also, looking at your code, there is nothing in there to tell me where you got those two word anagrams from.

    A better name would be:
    getEightPairsOfWordsFromTheWordDocumentingFromTheAir=
    ["ceding mount", "document gin", "condign mute", "induct gnome",
    "coming tuned", "gnomic tuned", "cumin tonged", "cum denoting"]

    You fail!

  2. Dan said,

    on August 6th, 2008 at 1:17 am

    Sharfah, I’ll concede your first point. “get” is better than “generate”. I’m not sure I agree with the second though. You don’t need to know where I got the words from ;)


  3. on August 6th, 2008 at 10:01 am

    [...] all about it here via New adventures in software Top blogs deconstructed, Real life photoshop., top 30 bits of javascript, Hottest jobs in IT or why [...]


  4. on August 6th, 2008 at 10:02 am

    [...] Read all about it here via New adventures in software [...]

  5. paan said,

    on August 6th, 2008 at 4:56 pm

    even though you got disqualified I’m still rooting for you to win the contest.
    I’m really am in the “less comment is good” camp.. but I don’t really think that no comment at all is good..

    anyway.. since they arbitrary chose the word “documenting” rather than say create a program that can take any word and create a 2 word anagram, using the word documenting as an example, it really means that the best way to do the program is your way..