Are there any coding style guidelines for LaTeX?

Question

I have been using LaTeX for a long time now, but still all my document files look a bit messy. Now I want to get rid of this bad habit and get some order into my code.

That is why I am wondering whether there are any coding style guidelines for LaTeX. Not necessarily anything official. It could for example make recommendations on how to format your code with respect to:

• Setting comments in the text/preamble
• Whether to highlight sections/subsections etc. by some comments
• How to indent environements
• How to organize your preamble to make it readable
• etc.

If nothing as such exists (yet), it would be great if you could just post how you do it if you think your code looks rather nice.

Answer 1

There was a talk at TUG'11 exactly about this: Didier Verna, Toward LaTeX coding standards:

The paper is available for TUG members only till the end of the year, but the video is available for all. Take a look: Didier has many interesting thoughts to offer. You might be also interested in Chris Rowley's talk at TUG'09. And please consider joining TUG: this gives you an immediate access to TUGboat papers and many other benefits (see http://tug.org/join.html)

Answer 2

This is how I would do it:

General

• indent by three spaces (I find that two spaces don't stand out enough...)
• use Tab to indent or hard code with three spaces

• use more new lines to structure code than less, i.e. prefer

  \newcommand{\mycmd}[1]{%
     \par\addvspace{\baselineskip}%
     \noindent
     My Text:~%
     \parbox[t]{0.6\textwdith}{%
        \textbf{#1}
     }%
     \par\vspace{\baselineskip}%
  }
  

  against

  \newcommand{\mycmd}[1]{%
     \par\addvspace{\baselineskip}\noindent
     My Text:~\parbox[t]{0.6\textwdith}{\textbf{#1}}%
     \par\vspace{\baselineskip}%
  }
  

  That will help to keep the overview and comment out small snippets of a definition to find errors.

Preamble

• one line per class option, e.g.

  \documentclass[
     ngerman,
     fontsize=12pt,
     draft
  ]{scrartcl}
  

• blank line between packages

• indent all code that belongs to a package

  \usepackage{xy}
     \xyset{
        x=2,
        y=3
     }
     \renewcommand{\xy}{...}
  

• blank lines between definitions
• use comments to structure the code and tell what it does — this will help to keep track of your code even when you take a look at it after some time.

Body

• Indent environment contents

  \begin{xyz}
     content
  \end{xyz}
  

• Set equations, floats and any other environments with commented blank lines

  Some text of a paragraph
  %
  \begin{figure}
     \centering
     FIGURE
     \caption{Nice figure}
  \end{figure}
  %
  more text of tis paragraph
  %
  \[ y = x^2 \]
  %
  last text.
  

• break all lines after approx 70–80 characters (instead of writing and writing till the editor makes a break). That makes it easier to find en error where TeX gives the line number.

• Set \footnotes on their own line and indent them – don’t forget to comment the end of the preceding line to suppress the space.

  Text with a footnote%
     \footnote{Text}
  more text
  

• use logical markup whenever some things appear more than once, e.g. define a macro to format names instead of hardcoding them with \textsc{Jon Doe}. That enables you to change it later very easily.

• use blank lines to set off headlines from regular text, e.g.

  \chapter{My Chapter}
  
  Text
  
  
  \section{My section}
  
  Text
  

Answer 3

one simple tactic that will make the body of your input more readable is to always start display material on a new line, and start another new line at the end of the display. break lines within display math so that the input breaks coincide with the line breaks in the output. (i've just spent a couple of hours "de-stringing" run-on input for a book, and my head is spinning.)

the suggestion to look at the video of didier verna's talk is an excellent one. do it.