How to Format Code in Research Reports

Question

I am currently writing a formal research report, and I'll be including code with this report.

Question: Is there an accepted way of displaying code in research reports? I'm thinking both in terms of font, spacing, et cetera, and whether the code should be displayed inside the document, or in an appendix.

The code will be JavaScript and PHP. None of the sections of code will be more than 25 lines (so they're mere snippets). There will be approximately half a dozen snippets. Each of the snippets will have a couple of paragraphs explaining what is happening in the code, and a discussion on its pros/cons.

I have no contact with the body to whom the report will be submitted to, and they have no published guidelines on how to format code (please do not question these points).

Any help considered and appreciated.

Answer 1

Well it depends on which style guide your paper is being written to comply to...

Usually code should be written in a monotype font so that it is easily readable (E.g. Lucida Sans Console or Courier New). This means that all letters take up the same space on the page.

When I have written bits for publishing I have indented the code 2.5cm from the side and given it a light grey background, in a Lucida Sans Console font... Following C style code indenting.

I would ask your institution if they have a style guide, but as you have a lack of this ability go with a popular style guide such as the Harvard system and make sure you follow the same format throughout.

Here is a list of journals from Google Scholar which display style: http://scholar.google.com.au/scholar?hl=en&q=PHP+SQL+programming+journal&btnG=Search&as_sdt=2000&as_ylo=&as_vis=0

Answer 2

I would say Courier font with standard text spacing and standard line spacing, all black text, proper indentation.

In terms of the code itself, omit import statements, comments are okay. You may want to add foot notes like {1}, {2}, inline in the code as a comment and reference below in the text that explains the code.

This paper has an example on page 6:

http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-1.pdf

Answer 3

If you are writing a research report, you should be using LaTeX.

I typically use the LaTeX vancyvrb package and the Verbatim.

However, another option is to use the listings package. It can input a file directly using the lstinputlisting command. It automatically numbers your lines and uses the _ character instead of the space character, but this is programmable. It's really quite nice.

Answer 4

This is my preference:

When writing inline, get rid of code that is irrelevant to the explanation (such as import statements as previously mentioned, but potentially also variable declarations that are "obvious" and the like). The goal of code placed inline should be for easy crossreference with the paragraph describing that code block.

Code placed in appendices should be complete (as in - you can put this into your compiler and press go).

Don't be scared of placing heavily cut down code in snippets, along with a reference to the appendix containing the full code - the appendix code is for someone to read/run separately. the inline code is for people to glance at and help understand the specific point of that section.

Answer 5

I realise that this is an old question, but do not forget to number the lines in your code! For one-liners, it's okay to skip numbers, but anything larger, they're almost required.

Answer 6

What JD and Ben said.

You should use appropriate, established syntax highlighting. Latex's listings package, mentioned by vy32, has syntax highlighting styles for both Javascript and PHP, as does the Pygments program, which outputs to, among others, Latex, HTML, and RTF.