Really Simple Guidelines to Write Great Code Samples
When a developer learns a new programming language or API, the first thing is probably to try out a HelloWorld sample. As said, real programmers don’t read documents. Although I don’t fully agree on that, it has some truth in it.
In my own experiences, I normally continue with other samples after HelloWorld one. When something is not quite clear, I check out the API reference or read some tutorials. Anyway, I am not telling you how to learn a new language or API, but trying to make a point here on the importance of code samples for the developers. In my opinion, samples are the most effective way to empower your users.
Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.
I think you would agree with me, there are too many bad samples. Here are some typical symptoms:
- Too much boilerplate code to a point that the code illustrating the API usage got buried. Typical boilerplate code includes extensive exception handling, GUI, logging, etc. Some samples even have a common library that could confuse your users totally.
- Too many API calls in one sample. You may need several APIs for a use case, but don’t aim one sample for multiple use cases.
- Too much object oriented. Object oriented programming is a best practice for application development. But it could confuse your developers sometimes.
- Dependencies on other APIs. To run the sample, your users need to install other libraries which may or may not need extra configuration or tuning. To understand the sample, users need to understand additional APIs. Extra burden, really!
- Of course, typical bad smells of programming which are not unique for samples. For example, bad naming, unnecessary global variables, using object attributes for passing values between methods, etc.
Now, how you can develop great samples? Besides the best practices writing great applications, you want to follow the following guidelines:
- Have a real use case in mind. With this, your users will find it more interesting and useful. And they can easily adapt the samples to their own projects. You should resist the temptation to pack more than one use case in a sample unless it’s a put-it-all-together sample, which is normally the last one of whole series of samples.
- Keep it short and to the point. You want to minimize any initialization and boilerplate code that you need in production code like exception handling, logging, etc. If you can use a file to make your point, don’t use database. If you are not showing a GUI API, don’t add GUI.
- As little dependency on other libraries as possible. You don’t want to have your users to install and learn these before they can run your sample. It creates better user experience than otherwise.
- Use procedural over object-oriented programming. A little against common sense? Although object oriented programming is a great way for coding, the procedure calls are better illustrating the API calls from users’ perspectives. In object-oriented programming languages like Java, you can simply pack your code in the main() and several other static methods.
- If you have a series of samples, you want to categorize them with different packages and advance them step by step.
Ideally, you also want to show the best practices using the APIs because samples are the best place to educate your users on best practices. For example, if it’s a best practice to terminate a connection when it’s done, you should do so in your sample.