Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm in a statistic course at Uni currently. We have to present reports on the findings along with the code we used. I'm wondering what is the best way to present this code in the reports. A separate page with a reference to the report or inline. Or something else?

Thanks

share|improve this question

7 Answers 7

If you're only referring to small parts of the code, place it on the same page where you're speaking about it. No one wants to read through more than page's worth of code by if they can help it.

For an immediate separation between code from English text, use:

  • a different font
  • a different background colour

An irrelevant aside: for subconscious bonus marks, use something like latex. As the people marking your report (most likely) would appreciate it.

share|improve this answer

In addition to @Jonathan's answer, some points from when I had to present code in a report:

  • Indent the code. This provides a dimension aspect to differentiate text and code.
  • Export the code from the editor in a manner that retains the syntax coloring.
  • When colors are used, ensure they print in a readable color range when printed in black & white
share|improve this answer

Do something like that and ....

Stick it on http://github.com/ or http://gist.github.com/ or something and include the URL!

If there any chance they will want to actually run the code to see how great your report, this will make it very easy for them to do that. They may appreciate the thought even if they don't actually run it.

share|improve this answer

How much code? A few lines, possibly up to a third of a page, works inline. More than that and you're probably better off putting it in an appendix.

share|improve this answer

I would use both: mention the most relevant part of the code inline (in small parts, all irrelevant details left out, perhaps just method signatures or parts,) then provide the full code or at least relevant code and context as appendix. (Other ways of presenting full code might be an option, online or a cd or something. That depends on the report and your target audience.) Inline code should be short enough to be just an illustration of the point you make in your text. The full code in the appendix should be extensive enough so anyone can check your conclusions.

Make code examples visually distinct and caption and/or number them, like you would with blockquotes of text, illustrations, graphs, tables etc. I would also mention where in the appendix the inline code fragment can be found.

share|improve this answer

In addition to other answers, I recommend using a variable-width font for discursive text, and fixed-width for code. Not only does this mimic the way code-and-copy are intertwingled in most books and online (hello Stack Overflow!), it also implies nicely who the intended audience of the text is for.

Variable-width font looks like it's meant for people. Fixed-width font looks robotic and like it's meant for machines--it actually hails back to when text was laid out in strict rows and columns on a screen, and very little attention was given to readability.

share|improve this answer
    
I think fixed-width fonts hail back to a time when we still used typewriters. ;) –  mipadi Mar 9 '11 at 14:21
    
@mipadi - Well, true! –  Dan Ray Mar 9 '11 at 14:43

It depends on how tied the code is to the report. If your report is primarily about your findings, then I'd just add the source code as an appendix at the end of the document.

If you're report includes details about the code or algorithms that you're using, then still include a full printout in the appendix, but include snippets of relevant code inline with the document.

If you're using LaTeX, I'd suggest using the Listings package for source code. This creates a nice frame around the code with a shaded header, with a monospace font and syntax highlighting for most languages, and you can label the snippets so that you can \ref{listing:foo} in your document.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.