Most of us have heard that a picture is worth a thousand words. Well, sometimes an example is worth a thousand words. Examples are like pictures in that they give a clear and visible snapshot of something that you are talking about. I am a software engineer and so I blog about programming on occasion. These are just a few tips I’ve learned about including code samples in your blog.
Keep It Small
When you would like to show a code sample keep it small and pertaining to the topic at hand. It can be quite daunting to try and digest and entire class file or program. Don’t worry about including your code in it’s entirety. Instead trim out several lines of code that clearly demonstrate the concept that you are discussing. It should be just enough to give the reader the basic idea. I also like to place elipses in front and in back of the sample to let readers know that it is an extract.
Label Your Samples
Label the code in your article or blog as Listing 1, Listing 2, etc. This will help the reader to quickly jump to the sample code when you refer to it in your writing. Some writers like to place all of their listings at the end of the article so that it doesn’t break up the flow of their narrative. I personally like to have the sample right there next to the topic it is being used for.
Syntax Highlighting
Since we are trying to clearly convey our concepts to the reader, why not make the code easier to digest as well. Most developers/programmers/code-heads/what-have-you use some sort of IDE (Integrated Development Environment) which provides them with syntax highlighting. These editors can make different parts of your code different fonts, colors, sizes, etc. For instance all of your comments can appear green and italicized while all keywords are blue and bold. This is invaluable for helping programmers quickly identify errors and also to easily navigate the code. There is a web service called GeSHI – Generic Syntax Highlighter that provides syntax highlighting to 3rd party applications. I use a WordPress plugin called WP-Syntax on this site which utilizes that service to highlight my code for me.
Keep It On The Page
I usually enclose my code inside a <PRE> tag or a <CODE> tag to maintain it’s formatting when viewed in the blog. Furthermore the plugin I use utilizes the <PRE> tag to do it’s syntax highlighting magic. This means that if you have really long lines in your code they will NOT wrap in your blog. So if your code stretches beyond the limits of the current page or section when in a <PRE> tag, then use a surrounding <DIV> to confine it to the size of the current container (page, column, etc). You can specify to use scrollbars on overflow so that readers can view all of the code. Alternatively you can manually add line breaks when needed and just format the code as you see fit.
Offer A Download
Finally, a nice touch to add to the end of your blog about coding is a download. This should be a full and complete example that includes all of the previous samples listed. It is also nice if it is a working example that your readers can simply compile and run without any problems.
Conclusion
I hope you’ve found some useful tips here for your blog. Do you have any tips to add to this list? Have you utilized code samples in your blog? If you’d like to leave your URLs in the comments I would love to come see the way you do it. Thank you so much for stopping by my blog!