Sample code for IoT development

When producing sample code for documentation, it can be easy to fall into the trap that what is written is “not production” and it can suffer from undergoing less scrutiny than code that is immediately destined for production systems.

It’s always worth remembering that developers reading your sample code will likely (perhaps blindly) trust that a given example is the right way to do things.

When you write sample code and technical documentation, you are acting as a teacher to developers you may not even meet or speak to.

The code written may well be simply copy-pasted into another application and any issues within it have left your sphere of control: the defect is now in another application, and may well propagate from there! The next developer on this third-party system is unlikely to look back to your original sample code, they’ll simply use the examples left in other places it has been implemented. Thus any original defect is amplified and propagated.

So how do we prevent this spread of issues? Simply by treating our sample code with the same care, attention and scrutiny that we give to live production code. It’s not a disposable script to test a feature out: it’s a chunk of code that will be used in ways you cannot yet imagine! It should still pass through QA, code reviews and sanity tests, and follow the principles of SSCCE.

SSCC stands for: Short, Self-Contained, Correct Example and sets out some principles for documentation and example scripts:

• Short (Small) – Sample code should be concise and readable
• Self-Contained – Ensure everything is included, ready to go.
• Correct – Copy, paste, (compile,) see is the aim!
• Example – Demonstrates simply the feature in question.

To keep these sample applications clean and small, effort should be taken to trim the sample to only the required code to be demonstrated. This helps reduce the cognitive load needed to understand the example, and allows another developer to follow the flow cleanly.

Example inputs and outputs, sometimes with dummy code help to keep the samples self-contained. Sometimes prerequisites are needed, but often these can be mocked up using static variables rather than needing full access to external systems.

Example code should compile in one step, run and demonstrate the feature with no other inputs needed from a developer. No tinkering with config, or multi-stage deployments!

We supply full sample code for features a client may want to integrate into their systems as part of our client and partner documentation portal.

With KeyScaler available on so many different platforms, often this code will form parts of a proof of concept, and sometimes may be written on a bespoke basis to demonstrate specific use-cases and combinations of technology. Sample code accelerates our clients path to implementation, and helps them get value from KeyScaler from day one.