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.

Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.

I think you would agree with me, there are too many bad samples. Here are some typical symptoms:

  1. 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.
  2. 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.
  3. Too much object oriented. Object oriented programming is a best practice for application development. But it could confuse your developers sometimes.
  4. 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!
  5. 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

Need a sample of writing samples? Please feel free to check out the samples of the open source vijava API project.

This entry was posted in Software Development and tagged , , , , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.

2 Comments

  1. Posted November 24, 2010 at 3:00 pm | Permalink

    Hi Steve,
    what a great post!
    I absolutely can confirm your ideas, from my own experience as developer as well as a teacher at the university.
    Keep on going, the vSphere Java API is a good source even for other technologies using VMware’s APIs!
    Cheers, Joerg

    PS.: Could you please email this post to your colleagues from the vCenter Orchestrator documentation team?
    (Their API documentation will definitly benefit from your rules :-) )

  2. Posted November 30, 2010 at 10:31 am | Permalink

    Hi Joerg,
    I am glad you like the post and confirm the ideas from both industrial and academic world. Thanks!
    Steve

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  • NEED HELP?


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.