The Basics - How to Easily Format Code Snippets

An occasional series looking at best practice for common documentation tasks and situations. 

Writers who document software will invariably have to document a code snippet or two in their careers.  This could range from the occasional line of CSS in a configuration guide every few years, right up to the full-on, nothing-but-code explanations of the full-time API documenter.

I'll be honest, this post isn't for the API specialists, but it is for those who only have to occasionally format a code snippet, or for those who are looking for a better way.  Those writers who document APIs will need to follow proscriptive standards and understand the code in order to provide clear, coherent information to their readers.  Those writers for whom code is something that people who can't write in a natural language write in instead - you know who you are! (and you're very welcome here) - may however find formatting code snippets a little daunting.

(In case you've never formatted code before, it's not as simple as just changing it to COURIER NEW.  Well, it can be that simple, but not if you want to do a proper job.  Code snippets will be read by people who code, so it should look like code.)

Fear not, my friends, for there is a simple way to format code. 

Your immediate option, if you have access to them, is to use the same tools as the developers.  So for formatting SQL you open up a query writer like SQL Server or dbForge Studio for Oracle, drop the SQL into a New Query window, and then copy and paste into your document.  You can do the same with code if you have access to an IDE like Eclipse or Visual Studio.

However, the problem with industrial tools like these is two-fold: Speed and Cost.  Industrial tools are not built to open in half a second 30 times a day; they're designed for heavy duty coding, and that makes them less than rapid at opening.  And although Eclipse is free, Visual Studio, SQL Server and dbForge Studio are not.  As I've discussed elsewhere, people should have the licences they need, and it doesn't seem a good use of your budget to spend large amounts of money on licences just so a writer can format code a bit quicker.

Besides, who wants to have to open a SQL application, and an IDE, and an HTML editor, and an XML editor, and a CSS editor several times a day?  If only there was a lightweight, fast, free, easy to use application that would open these files with the odd extensions automatically and quickly, and just format the code for us!

Well, there is.  It's called Notepad++ and seriously, it's awesome.  

If you're not a particularly technical person, Notepad++ might have passed you by, but it is essentially the Swiss-army knife of coding and it is free, lightweight, very quick, and it will format whatever legitimately extensioned code file you give it with ease.  Well, let me rephrase that: The list of programming language file extensions it supports is very large, and the chances of you working on one that isn't supported by Notepad++ is low.  All you have to do it right-click a file and Open with Notepad++ - or set Notepadd++ to be the default program for opening the code files you need to format - and it'll do the rest.  

Here's an example .xml file opened in standard Notepad:

And exactly the same file in Notepad++:

That is out of the box, default functionality.  I created a new text file, wrote some XML in it, saved it, renamed the file to XML.xml, and opened it in Notepad++.  All you have to do at this point is cut and paste the code into your document, and you're good to go.  

I'll come clean with you on one thing: If you want it to auto-indent code that hasn't already been indented, you will need to install a plugin.  But that's not too tough an ask, especially if you deal with existing, indented code. By default Notepad++ will change the indent of the TAB button to the standard indent for whatever code you're working in, so as long as you haven't got long screeds of unformatted code to work with, indenting it yourself is very easy.  There is also a very active user community, as Notepad++ is used by millions of people around the world, so if you have questions there's a good chance the answer is available already, or someone will answer it for you if you ask on a forum.

If you've got another tool which you think is as good as or maybe even better than Notepad++, please share it in the comments.