Let’s first take a quick detour:
The Software Engineering field thrives on Open Source Projects that is built for and by the people who are part of the community. This is a feature that is unique to the Software Engineering field and not quite common in other Creative or Science streams like Aeronautics or Biology etc. You do not see Open Source prototypes of Airplanes do you? May be because Software innately is Virtual and it makes it easy to duplicate and share. This ecosystem of constantly hitting a wall in some sphere of technology, coming up with revolutionary ideas to solve that problem and sharing that knowledge with the community is just beautiful. I’ve personally gained a lot of inspiration from projects like the Spring Framework, Angular etc. and myriad of cutting edge technologies that are constantly churned out by the Apache Software Foundation (ASF).
Back to the topic on hand:
Take a look at this Tutorial from Angular.io, the official home page of the popular Angular Framework. I’ve been closely following the evolution of the Angular Framework as well as how their documentation has also evolved in the past few years to its current state.
https://angular.io/docs/ts/latest/tutorial/
As you can see the above tutorial does a bang up job walking a reader through a small project to introduce core fundamentals of Angular. The tutorial is augmented by a Live Example. The live Example running on Plunkr shows the source code and its fantastic expect for the fact that there are no test cases bundled with it.
It’s the same deal with the Spring Framework and myriad of other Open Source projects.
Here’s why live examples and code documentation must be bundled with test cases
- To emphasize to the reader the value of writing automated tests
- To “teach” the habit of writing test cases: Demonstrate the various ways the Code Sample can be tested. After all the goal of such source code is to help the reader borrow the ideas and implement them in their own projects. Showing well written test cases teaches the reader to write tests in their own implementations.
- To verify your own work! The code sample itself needs to be tested. Do you really have to manually verify that your code works instead of using automated test cases to do the verification and validation?
I hope that Open Source projects seriously consider revising their approach towards their documentation and incorporate well written Automated tests in their Code Samples and wherever it makes sense. (Unit, Integration and others as appropriate)
The online HTML editor now supports the use of an external CSS file to be applied to format the content of the visual preview of your document.