122

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.

2
  • 4
    related (duplicate?) question: tex.stackexchange.com/questions/12171/…
    – doncherry
    Jan 11, 2012 at 17:09
  • 1
    LaTeX should, for the most part, be treated in the same way as any code; concise comments. LaTeX benefits from being rather readable anyway, so in many cases it isn't necessary to add much. Perhaps a few % characters to highlight new sections. Only indent environments that are composed of few lines, and for which structure is important, such as figures and tables. Don't indent paragraphs, it gets tiresome. Use some common sense and you won't go far wrong, especially with synctex.
    – qubyte
    Jan 11, 2012 at 17:17

3 Answers 3

70

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

enter image description here

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)

5
  • 2
    Okay, accepting your answer - with the condition that you add the paper once released :-). Thanks!
    – Ingo
    Jan 13, 2012 at 8:29
  • 4
    Thanks. I've added the paper link. The present TUG policy is that papers in TUGboat are members-only for one year, and go to the general public after all. If you are not a TUG member, I urge you to join (I guess it is my duty as a board member to ask people to join the organization :). See tug.org/join.html
    – Boris
    Jan 13, 2012 at 17:04
  • 2
    Didier Verna's talk is really interesting, but I just wanted to clear something out. At 8'40'' and later at 13'20'' in the video, Didier says he is a maniac, but I don't think he meant he's a crazy person. What he most probably meant was that he has his little ways (which is what maniaque means in French) when it comes to code formatting.
    – jub0bs
    Oct 19, 2013 at 8:40
  • 5
    i just changed the link to the paper to access the "open" version. re earlier comments, i join boris in encouraging tex users to join tug (or another tex user group), and regarding didier, i'm willing to accept his characterization of himself -- he wouldn't go around spreading untruths (big grin!), and his talks are always interesting. Nov 26, 2013 at 16:51
  • Could this answer be considered, as of June 2021, still an up-to-date answer? (I have the same question of the OP, but with doubts about creating a new one)
    – Chris
    Jun 25, 2021 at 23:09
48

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
    
8
  • What are your indentation rules? Using tabs for example seems to be too much in many cases, as for nested itemize lists indentation quickly grows out of hand.
    – Ingo
    Jan 11, 2012 at 17:18
  • 4
    Ah! My mistake. Really should clean my glasses more regularly.
    – qubyte
    Jan 11, 2012 at 17:35
  • 19
    When using a version control system another policy is sometimes used: put every sentence on one line and let the editor do the wrapping but end each sentence with a newline. This helps to get meaningful differences between documents as they are computed by diff tools which work on lines. This is important when working with several people and you rely on diff tools for the merging of changes. Jan 11, 2012 at 18:11
  • 1
    @tehingo - Most editors will let you set your tab size.. Jan 11, 2012 at 20:15
  • 5
    I think it's best, if possible, to put floats between paragraphs (or any other place where it's fine to leave a blank line above and below the float). That way, if you have to cut and paste the float later, you're less likely to accidentally cut surrounding text or start a new paragraph where you don't want to.
    – MSC
    Mar 14, 2013 at 18:22
18

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.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .