1

I write a report and must think about the reader. The report has some code and some illustrations. I wonder how to display the code readably. I now mix the fonts Times New Roman 12 for normal text with Courier 11 for the code. But I could write the code in LTL, linear temporal logic instead, which I think looks the best but it is not really necessary and takes a long time.

Do you think that is will be good to just keep times new roman 12 for the normal text and courier 11 for the code?

1
  • Does your institution have a style guide that you're supposed to follow? If so, which one? May 11 '17 at 15:43
2

Unless your institution has a specific style guide for writing and formatting code (which, by the existence of this question, I assume you do not), speaking as someone who writes technical documentation to software:

  1. The font which I generally use is Cambria or the Serif-family of fonts, size 11, 0.5 spacing for text. Nevertheless, I have specifically been instructed to use these fonts.

  2. For code, use font where exactly each character takes up the same amount of space as any other character. Source Code Pro is a good example of such a font.

  3. Code should stand out or otherwise be easily distinguishable, so put in in a box. Above all (as mentioned above) code formatting should be like it is found in an IDE or text editor, so each character takes up the same amount of space. For example,

This is a program which prints "Hello World!" to the console.

String s = "Hello World!";
System.out.println(s); 

I've usually been hesitant to include comments in the code blocks, especially if your document is already explaining what the code does.

Another thing which you could certainly do is simply take screenshots of code from your IDE/text editor, crop it in a image-editing program and simply paste the resultant image into your document editor. This can be nice, since usually IDEs have things such as line numbers which are otherwise unavailable in pre-formatted text.

Unfortunately, I cannot offer much more advice, since when it comes down to questions about technical writing, the answers is "it depends". Different institutions have different needs, and, to be honest, if they haven't given you a decent idea of how they want something formatted, either they're acting unprofessionally or aren't too fussed about details as long as the message gets across.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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