Invariant Properties

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?

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:

• 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.)