The Friendly Coder

On software development and technology

Art of Code Snippets

One habit that nearly every talented software developer I have had the privilege of working with has mastered is the use of code snippets. Read on to find out why I think that is and to discover some tips for using them effectively.

What are code snippets?

For the sake of discussion here I am going to assume that a snippet is any functional piece of program code that performs a specific task. Typically snippets are short and focused blocks of code that represent one small portion of a larger function or program. Snippets differ from pseudo-code in that they can actually be compiled and executed directly in the associated language.

Good code snippets tend to embody the following characteristics:

  • Small number of lines of code (the smaller the better)
  • Have few, if any, external dependencies
  • Exist in a stand-alone project configured for the sole purpose of running the snippet
  • Can be built and executed in a clean host environment with few, if any, environment variables, compiler options, etc.

How are they used?

From what I have seen, inexperienced developers tend to follow some common workflow patterns. For example, they will often experiment with new language features or new external libraries within the context of a complex application, often in supposedly production-ready code. Also, when they are debugging existing code they tend to guess their way to a solution using trial-and-error, making miscellaneous changes to the code until they can alleviate the erroneous behavior.

Contrast this with what more sophisticated developers often do by leveraging code snippets. If there is a new language feature they want to use, or a new library they are considering using, they often start with “throw away” code. Essentially they write short pieces of sample code, often in a very simple and clean project or folder that can be built and executed quickly. These snippets tend to focus on one specific concept (one function call, one new language feature, one simple functional block, etc.).

Similarly, if there are extremely complex interactions at play with multiple application subsystems they will often attempt to reproduce a bug using a similar snippet template to allow them to isolate the parameters at play that cause the bug so as to evaluate several potential solutions to the problem without having to deal with the added complexity that the other less-relevant pieces of application code introduce.

Why are they effective?

  1. Snippets, in and of themselves, are effective primarily because they tighten the feedback loop for the developer allowing them minimize the time required to get to the root of a problem or to gain a real world understanding of the behavior of a piece of code. This is due not only to the decreased compilation time (for compiled languages like C++) but also due to the decreased effort required to develop a clear understanding of the code due to the reduction of complexity in the snippet.
  2. Experienced programmers develop an appreciation for the fact that there is often a discrepancy between the documented behavior of a system and its actual behavior. Thus, for non-trivial language features and functional code blocks, it often yields more pragmatic results to actually try out sample code in an isolated environment so as to be certain the actual behavior is as expected.
  3. More generally, as time passes experienced developers (and experienced build masters) begin to realize that the sheer number of technologies one has to be proficient in to do their job well tends to increase. Also each one of those technologies will tend to undergo many changes and improvements over time. Attempting to be pro-active and keeping up with these trends is a daunting task. Thus we need to develop skills that allow us to work more efficiently to help save time and effort. By mastering the art of code snippets we can ensure that the quality of our code craftsmanship stays solid over time as things change.
  4. Another interesting benefit achieved by the process of preparing a code snippet is that you are forced to think through the code you are looking to understand or the problem you are looking to solve in a different way which often reveals useful details about the original code that may not have been obvious otherwise. The act of taking a complex piece of code that has a bug in it, stripping the code of all non-essential bits, and leaving just the section that you believe contains the bug will often give you more information about the cause of the problem and thus help you resolve it in a better way than you may have done otherwise.

When should you use them?

Many of the code samples you will see in the articles on this site, most notably those tagged as gotchas evolved from the use of code snippets in a production environment. Further, often snippets can lend themselves to good programming practices such as refactoring and test-driven development (some unit tests mirror the snippet pattern).

For example, declarative languages like Ant and MSBuild, are often fraught with convoluted behavior that is often non-intuitive. Short of learning the complex internal implementation details of the associated run-time environment it is often impossible to know the actual behavior of the system based on intuition. I personally find myself opening up an instance of my favorite text editor preloaded with a sample project file allowing me to quickly draft a sample build target to test out those assumptions.

Similarly, C++ is a large and complex language, with many little nuances that can easily get the most experienced developer into trouble (just read the first chapter in any of the several texts by Scott Meyers and you will see). As such I have found it useful to validate my assumptions regarding the behavior of the language and the key libraries used such as BOOST and STL. For this reason I typically have a Visual Studio project saved nearby with a trivial main function that I can use to mock up snippets of production code to ensure things work the way I expect.

What does this have to do with C.I.?

Well, as build master you will likely be working with a wide variety of tools, languages and technologies including programming languages, build tools, scripting languages, version control systems and continuous integration systems. You will realize very early on (if you haven’t already) that it is not possible to stay current with all these tools. As such you will benefit greatly by using snippets to debug problems on your build system and to help you develop an understanding of these tools without investing the time required to take a course or read books on each one.

Final words

I hope I have given you a few things to think about the next time you find yourself tracking down some unexpected or non-intuitive behavior in your next programming project. For those of you that have already experienced some of the things I’ve discussed here, I would love to hear from you. Add a comment describing your experiences, maybe with some examples of how code snippets have worked well for you (or perhaps some examples of how they haven’t worked for you).

Leave a Reply