IT SOLUTIONS
Your full service technology partner! 
-Collapse +Expand
Tech Writer
Search Tech Writer Group:

Advanced
-Collapse +Expand Tech Writer Store

Prestwood eMagazine

September Edition
Subscribe now! It's Free!
Enter your email:

   ► KBRole-Based T...Technical Wr...     Print This   
Go To Random Article
  From the February 2009 Issue of Prestwood eMag
 
Tech Writer Technical Writing:
Guidelines for Good Sample Code
 
Posted 5 years ago on 1/25/2009
Take Away:

Sample code often provides the quickest, clearest way to learn how an SDK works. If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing good production code do not apply to writing good sample code. Some techniques, such as comments and clear variable names, apply to both production code and sample code. However, there are good reasons to use hard-coded values in sample code, which should be avoided in production code, and there are good reasons to avoid object-oriented designs when writing sample code.

KB101850



Introduction

Whenever you need to explain how to use a Software Development Kit (SDK), the first thing you should do is write some sample code. Even if you write excellent technical content, sample code provides the quickest, clearest way to learn how an SDK works. In addition, sample code can be pasted into production code as a baseline and then modified by the developer.

 

Sometimes sample code will stand alone as an independent download. Other times, it is bundled with an article that explains how it works. If you are writing API reference material, then you may want to take snippets out of your sample code and use them in the reference material. This technique will generally result in better sample snippets than if you create the snippets just to demonstrate the API.

 

If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing production code do not apply to writing good sample code.

 

Effective sample code should follow these guidelines:

 

  1. Relevant information should be grouped together.
  2. Clarity is more important than efficiency
  3. Simplicity is more important than a good-looking user interface

 

Let's apply these guidelines to specific elements of software.

Hard-coded values

Do: Use hard-code values in sample code.

Every programmer knows that they should never use hard-coded values in their code. Those values should be turned into constants and put somewhere that's easy to find in case someone wants to change them. So you may be surprised to hear that you want to use hard-coded values in sample code. Why? To group all 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, then 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.

Comments

Do: Have at least one comment for every 5 or 10 lines of code.

Comments are obviously good for both production code and sample code, but in sample code, they are critical. 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. These comments can be several lines long if required.

 

In general, you should have a line of comment at least every 5 or 10 lines of code. However, there are some exceptions to this guideline. Code that is extraneous to what you are demonstrating does not need so many comments. If you are writing a small snippet with just a few lines of code, you might not need comments at all. If you are providing a very large sample that is more like production code, then it may be more practical to lower the number of lines of comments.

Variable, Class, and Member Names

Do: Use meaningful, clear names, even if they are long.

For both production code and sample code, variable, class, and member names should be clear. In sample code, though, you should take this idea farther 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 make even the smallest variable name have meaning, and do not -- no matter how much you are tempted -- use meaningless variable names like "foo" or one letter names.

Object Oriented Programming

Don't: Use object-oriented design, unless it is necessary.

Object oriented programming is one of software engineering's best inventions. You may be surprised to learn that although it is highly desirable for production code, it is in fact generally not desirable for sample code. The reason is that object oriented distributes functionality so that data and functions are grouped together and it uses inheritance to cut down on duplicate code. Remember that 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. So 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.

 

There are exceptions, of course. Some SDKs require object oriented programming to function properly. Very large samples that are more like a production application may also need object-oriented design. Just be mindful that the user wants to see all the necessary information in one class if at all possible.

Functions and Methods

Do: Group functionality by function or method.

One of the first lessons of good software design is to encapsulate functionality in functions and methods. For production code, this adds clarity and reduces duplicate code. It's also good for sample code, because it can create a block of code that developers can simply copy-and-paste into their own code and us as-is.

 

You may also find in your sample code that you need a large number of lines of code to get your sample to run that are not relevant to the APIs you want to illustrate. In this case, it's a good idea to try to encapsulate those irrelevant lines of code into a function or method so that developers can more easily ignore them.

 

User Interfaces

Don't: Write a lot of unnecessary user-interface code to make things look good.

Unless the SDK specifically works with user interface elements, you should keep your user interface as simple as possible. Even though it may make your sample look primitive, user interface code can take up a lot of space and dilute the important lines of code that you want to be demonstrating. Developers aren't concerned about whether your sample looks slick -- they just want to be able to understand how things work.

 

If there is no way to get around having a lot of lines of code for your user interface, then package them up into separate functions that are easy to ignore.

 

Large Samples

Do: Relax these guidelines and create something more like production code.

Occasionally you will be asked to work on a very large sample as a demonstration project. An example of this would be Microsof's Duwamish Books sample. These kinds of samples are more like production code, and therefore these guidelines can be relaxed to some degree. Object-oriented programming is probably more appropriate, as well as a good-looking user interface, and you would write a few comments per method, rather than every 5 to 10 lines.

Conclusions

Writing sample code is one of the most effective ways to communicate to developers on how to use an SDK. Following simple guidelines to group relevant information, emphasize clarity, and reduce unnecessary lines of code, will make it easier for developers to grasp the concepts that you are demonstrating. A good piece of sample code can be used by itself, in combination with an article, or can be split up into snippets as part of API reference documentation.


About the Author

Peter Gruenbaum is the President of SDK Bridge, a company that specializes in highly technical and training. He has a background in physics and software engineering, and has worked as a programmer writer since 2003.


Comments

1 Comments.
Share a thought or comment...

Anonymous
Comment 1 of 1

Excellent insights, Peter. We need you over here at Venafi!

---
Derek
Posted 30 months ago
 
Write a Comment...
Full Editor
Sign in...

If you are a member, Sign In. Or, you can Create a Free account now.


Anonymous Post:

Enter your name and security key.

Your Name:
Today's security key = P196A
Enter key:
Article Contributed By Peter Gruenbaum:

Peter founded SDK Bridge to bring together his love of technology and writing. He has worked as a programmer writer to describe technologies as diverse as the Tablet PC, mobile phones, and Live Framework. As a software developer, he has written software using Tablet PCs, Augmented Reality, 3D visualization, and computer-aided design. At Red Llama, he created a program to teach creative technology classes to low-income youth to inspire them to consider technology careers, obtaining grant money from the Gates Foundation, Microsoft, and others. This program has now become the "Software Development for Kids" project at SDK Bridge. Peter received his BA in Physics from the University of Chicago and his PhD in Applied Physics from Stanford University .


 KB Article #101850 Counter
9552
Since 1/25/2009
-
  Load Time=less than 1 second.
 
Print This

KB Post Options:
You do NOT have KB edit
rights to this post.
-
 
Have a question? Need our services? Contact us now.
--Mike Prestwood

Call: 916-726-5675

email: info@prestwood.com


-
 
Connect With Us...
PrestwoodBoards
Join Us!
Facebook
Like our page!!!
Twitter
Follow us!
LinkedIn
Join Group
YouTube
View channel.
Go ahead!   Use Us! Call: 916-726-5675 


©1995-2014 Prestwood IT Solutions.   [Security & Privacy]   Made in the U.S.A..   No H1-B.   No offshoring.