Do You Have Tutorial Unit Tests?

I haven’t posted much recently because I’ve been busy with my new job. This brings up an interesting question – you are busy with a new job a lot when you’ve been doing 6- and 12-month contracts. What works and what doesn’t?

What is your learning style?

learningstyles

 
Depending on the source there are between four and seven learning styles. This is an important consideration since people will retain little or no information if it’s not presented in their strongest learning styles. Successful students learn how to re-present the information in their own preferred style but it’s not always possible.

(An example of re-presenting information? By the time I returned to graduate school I realized that I, like many people, retain information much better if I write detailed hand-written notes even if I never look at the notes again. The kinesthetic memory of merely writing the notes dramatically improves my retention. This isn’t true of notes I write using a keyboard but that may be generational.)

If you want to reach everyone in your audience you should provide the information in multiple formats. The approach recommended in my graduate software engineering class was to use three approaches:
learning_styles_001_h

  • Read textbook or documentation
  • Attend lecture, ideally with demonstration
  • Do lab exercises

It doesn’t matter where you start, just that you touch all three (or four) approaches. Most software people will probably be readers (Trust the Source, Luke) but a sizable minority will want to start with working code, play around with different values, and only look at the source code once they have a general idea of how it works.

This tells us what we need in order to bring new team members up to speed most quickly and efficiently. We should provide source code – but tightly written to focus on the key classes and methods and not the clutter – and we should provide a sandbox where the source code can be played with. What happens with different enumeration values? When optional filters are added or removed? You get the idea.

What is a tutorial unit test?

The concept of a tutorial unit test should now be obvious. They are unit tests – small bits of code that can be run independently in the IDE – but stripped down to the essentials. The purpose is to educate, not test functionality, so you want to keep things as transparent as possible. That could mean things like loading key values from a resource bundle instead of using the much more complex “real” classes used in the rest of the system.

(Those “real” classes would be a good subject for their own tutorial unit tests.)

Another difference is that you want to cover as many layers as possible. For instance if you’re using Spring Data you probably don’t want to write any “real” unit tests below that level. You’re creating dependencies on the underlying data layout without any gain. That’s different when you’re learning the system – many of us learn best by being able to play with raw SQL talking to a test database instead of reading dry ER diagrams.

Finally it should go without saying that these tests should be heavily documented for “what” and “why”. (The code itself shows “how”.) Some good questions:

What is this test showing me?

I don’t need to be told that the test is showing how to read and update a custom index file. I want to know why we are maintaining a custom index file. I don’t need to be told that the test shows two objects being merged into a third, I need to know why we are merging these records. Who calls this code?

Why do I care?

Now that I know what the test is showing me, why do I care? What type of JIRA tasks will bring me to this code? Is this general knowledge, e.g., to get a better understanding of the data model, or is it something I’ll use to fix bugs or add features?

What do I need to look at next?

Code does not stand alone – it has dependencies and collaborators, it is a dependency for others. Sometimes we’re the only user and have a lot of flexibility, sometimes it’s subject to a contract with others. Who? How likely are the dependencies and collaborators to change?

Where do tutorial unit tests live?

I would recommend a separate maven project. It makes it clear that the unit tests should not be run as part of a normal suite and it’s a convenient place to hang additional documentation.

Edited to add: I also end my tutorial unit test class names with “Tutorial”, not “Test”. This ensures they aren’t picked up during the build process and makes it clear that they’re tutorial classes, not test classes. If you do this it’s a lot safer to put the tutorial classes in the main maven project. I still prefer the separate package if possible but that’s largely a desire to minimize clutter in my workspace.

(Image sources: http://lsuagcenterode.wordpress.com/2011/08/16/incorporating-learning-styles-into-program-design/, http://www.frbatlanta.org/pubs/extracredit/11fall_learning_styles.cfm.)

Reference: Do You Have Tutorial Unit Tests? from our JCG partner Bear Giles at the Invariant Properties blog.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

Leave a Reply


two + = 8



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books