Loading ...
Sorry, an error occurred while loading the content.

1763RE: [agile-usability] Re: documenting the UI in an agile environment

Expand Messages
  • Desilets, Alain
    Dec 1, 2005
    • 0 Attachment
      Message
      This is a different level of documentation, but I find nowadays, I mostly document my code by:
       
      A) Using long and verbous but highly communicative names for classes, variables and methods. It's not uncommon for me to spend 2 minutes thinking about what the best name is for a method. It's also common for me to change the name of that method half a dozen times over the course of its life, to keep the name in synch with changes in its actual functionality.
       
      B) Writing unit tests that read as a sequence of examples. For example, I once wrote a small "searh engine" to index words contained in a string. The list of tests for that class looked something like this:
       
      test_This_is_how_you_create_a_WordIndex
       
      test_You_can_use_WordIndex_to_index_and_retrieve_documents_based_on_their_word_content
       
      test_In_the_contents_of_the_document_words_are_delimited_by_non_alphanumeric_characters
       
      test_Indexing_and_retrieval_are_case_insensitive

      test_You_can_define_stop_words_which_are_ignored_in_retrieval
       
      test_WordIndex_deals_correctly_with_French_content()
       
      etc...
       
      Each of those was the name of a test method. The code for each test method was a small snippet of code that provides an example of how to do use WordIndex to carry out a particular task. For example, the code for the second test method might read something like this:
       
       public void test_You_can_use_WordIndex_to_index_and_retrieve_documents_based_on_their_word_content() {
        index = new WordIndex();
        index.indexDocument("doc1", "this string is the content of the first document");
        index.indexDocument("doc2", "this string is the content of the second document");
       
        HashSet retrievedDocuments = null;
       
        retrievedDocuments = index.retrieveDocsWithAllWords(new String[] {"first", "content"});
        assertEquals("Wrong set of documents was retrieved", justDoc1, retrievedDocuments);
       
        retrievedDocuments = index.retrieveDocsWithAllWords(new String[] {"content"});
        assertEquals("Wrong set of documents was retrieved", doc1AndDoc2, retrievedDocuments);
      }
       
      The beauty of this approach is that the examples provided by the TestCase are garanteed to be correct, because I run them hundreds of times of day, and fix any bug they reveal as soon as I find them.
       
      I find with these two techniques (meaningful names and readable example-like test cases), I can limit my documentation to "code maps", i.e. simplified maps that explain at a very high level how certain parts of the code hang together. I only do this for parts of the code that are complex and hard to understand.
    • Show all 15 messages in this topic