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.)
| Reference: | Do You Have Tutorial Unit Tests? from our JCG partner Bear Giles at the Invariant Properties blog. |
