At one time, sample code was supplied only for SDKs for a particular programming language. Today, with the popularity of web APIs, sample code is often provided in several languages. Indeed, the beauty of web APIs is that they can be called from almost any language—but that’s also their curse. You cannot possibly provide sample code in all languages that can make HTTP requests, so what should you do?
Granted, your developer team probably understands the principles of writing good code, but what they may not realize is that some of the good practices they have learned for writing good production code do not apply to writing good sample code. For example, clarity is more important than efficiency.
Effective sample code should follow these guidelines:
- Prioritize sample code by supplying it in the most utilized languages
- Group relevant information together
- Emphasize clarity
Let’s apply these guidelines.
Prioritize and Personalize Languages
You can’t write sample code in all of the languages that can call your API. What you can do is take the time to determine which languages your API coders are using the most. Focus on as many of those languages as you have the budget for.
Having said that, be aware that most Java programmers would rather not have to look at Python code. Your User Interface should be sophisticated enough to allow the user to select one language and display all sample code in that language. A good example of this is Stripe documentation, which uses tabs to display various languages.
Go Beyond Just Making HTTP Calls
Anyone can look up how to make an HTTP call in a given language and pass in the right parameters. Having sample code that does only that is not especially useful. Instead, think about what your API does and how the sample code could demonstrate common tasks. For example, sample code that returns a user profile could then construct a string to display information about the user, such as first name and last name. Another example would be a common workflow task where data from one request is used as parameters in another request.
Use Hard-Coded Values
Every programmer knows not to use hard-coded values in code. Those values should be turned into constants and put somewhere that’s easy to find in case someone wants to change them.
You may be surprised to hear that you should use hard-coded values in sample code. Why? To group relevant information as closely together as possible.
If you follow good practice for production code and define all of your constants at the top of your file, when developers look at the line of code that uses the constant they have to scroll to the top of the file to find out what its value is. That’s wasted time and effort. Strings, integers, hexadecimal values and other simple values should all be hard-coded right where they are used. Exceptions should be made for API keys and access tokens, which are expected to be different for each developer using the API.
Include Plenty of Comments
Comments are obviously good for both production code and sample code, but they are critical in sample code. Every class, Function or method should have at least one comment line explaining what it is or what it does. You should use comments anywhere that the code is not obvious, especially if you need to document a work-around or something equally unusual. In general, you should have a line of comment for at least every five or 10 lines of code.
Use Meaningful Variable, Class and Member Names
For both production code and sample code, variable, class and member names should be clear. In sample code, though, you should take this idea further than in production code. Remember, clarity is more important than efficiency. Long, unwieldy names can be a problem in production code, but they are usually worth it in sample code because of the added clarity. Try to give even the smallest variable name meaning, and do not—no matter how much you are tempted—use meaningless variable names like “foo” or one-letter names.
Don’t Use Object-Oriented Programming
Object-oriented programming is one of software engineering’s best inventions. You may be surprised to learn, therefore, that it is generally not desirable to create your own classes for sample code. Why? The object-oriented model distributes functionality so that data and functions are grouped together, and it uses inheritance to cut down on duplicate code.
But one of the fundamental principles of good sample code is that relevant information should be grouped together. Object-oriented code tends to distribute the relevant information among various classes. Developers may end up searching through an inheritance hierarchy for what a method does, which only serves to waste time and break their train of thought.
Don’t Get Too Close
It’s tempting to have the development team that created the API write the sample code. After all, who knows it better? But the fact is, they are too close to it. They will forget to use comments to explain things that are obvious to them, or create code that reflects how the API is built rather than how it’s used.
If you can, get someone outside of your organization or company to write the sample code. They will have a better understanding of what it’s like to be using the API as an outsider, and their sample code will reflect that understanding.
Writing sample code is one of the most effective ways to communicate to developers how to use an API. Following simple guidelines to prioritize languages, group relevant information and emphasize clarity will make it easier for developers to grasp the concepts that you are demonstrating. And the best sample code is written by a developer from outside the group that created the API.