cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

Sample Code Standards: Scope, Function, Clarity, and Style

124
Views
10
Helpful
1
Comments

There are a few topics I would like to make sure we all have in mind when writing sample code: Scope, Function, Clarity, and Style.

Scope

Don’t do more than the developer can handle.

Code samples can range from Basic to Advanced.  A simple, basic sample shows a single concept clearly and directly.  For example, it might be a one line code snippet that shows an example of making a method call.  A complex, advanced sample shows multiple modules, assets, concepts, and the communications between them all at the same time.  An example of this might be an entire application sample with assets and hundreds or even thousands of lines of code.  Obviously there is a wide range between simple and complex that our code samples can fulfill.  Small inline code samples are often found in the developer documentation itself whereas medium-to-large samples come bundled separately as a unit or as part of a Software Development Kit.  When writing a sample, decide early on what the scope is for your sample.

Understanding the scope is important because it impacts the audience that can consume it.  Put yourself in their shoes.  Do I have the skills needed to execute on this?  How much time will it take to understand how to use this sample code?  What should I learn from this?  A healthy collection of sample code will have samples from all ranges from basic to intermediate to advanced with code sample collections to match.  Simple code gives them basic understanding of how a method might be called where an intermediate sample could introduce the method call in larger functions or more situations of common usage.  A complex example might show how the method is called or modified against common patterns or in more advanced situations that are likely to come up like polymorphism, threaded execution, or dealing with exceptions and failures.

Before you even begin to write the code, have some bearing to your own levels of “Basic” to “Advanced” – it will be undoubtedly different from your audience.  Be as clear about the scope of the sample and run it by others to gauge the complexity.

Function

Make sample code functional.

Answer these key questions about function before writing the sample code: What does the code sample do? How does it do it?  What does it need to work?  How do I show that to someone?

To maximize our spread, we should be very aware of what functionality we are exposing through sample code.  In some respects, it is similar to code coverage.  What base of functional code are we exposing through code samples?  To understand that, we need to understand the function the sample code is serving.

Since technology function is often “the thing” developers are really searching for in sample code, it is important to make it clear what the code does and does not do and what it takes from the developer to be successful.  As an example, if the sample code showed how to establish a video call via Jabber Guest, it should not only explain how that is accomplished but should clearly describe what technologies and skills are required.  That is the “function” of the sample code: express how to use other functionality.  I know it sounds obvious but it is easy to lose sight of when you are head-down just making it work.

Finally, we all know that there are often several ways to do the same thing in code.  Sometimes it is useful to show them the same functionality from different approaches to reinforce how and why to use that functionality.  If one way should be preferred to another – tell the developer why.  It is good form to inform the developer of alternate paths – or at least be aware that they exist.  The function of sample code is to inform.

Clarity

Be clear not clever.

When writing sample code, align anything you create to readability and comprehension.  This does not necessarily mean more comments – this means clarity in what the code is actually doing.  If you want to deeply document and comment upon a body of code just make sure that you advertise it at “annotated” code so the developer knows what to expect from the content.

Once again, put yourself in their shoes.  Does this make sense?  If in doubt, send the code to peers or even someone non-technical for review.  If you find yourself having to explain too much, you may have to simplify the approach or reduce the scope to improve clarity.

Style

Use style to unite rather than divide. 

Style is sometimes a religious issue among engineers.  Within Cisco each technology group does tend to have adherence to their own standard.  That is well within their right, but we have our own group of external developers to communicate  to.  The best thing we can do is avoid any frustration and extra work by using existing coding standards.  This is really to have a common language across all of our sample code that is helps readability and keeps things consistent for the developer trying to navigate our content.

The following sources should be referenced when writing sample code.

If you haven’t already, you should also review the Engineering Communications Style Guide as a lot of the concepts translate into writing sample code.  Keep in mind: We are communicating to engineers through sample code.

Comments
Enthusiast

Great advice for a dev evangelist that is writing sample code to make it easier for devs to innovate/develop on our platforms

Content for Community-Ad
August's Community Spotlight Awards
This widget could not be displayed.