Styleguide for LaTeX similar to the Google styleguides?

Question

Even though I don't work at Google, the Google Styleguides have been very helpful for me in adopting consistent, readable style conventions for my code. Unfortunately, there is no Google Styleguide for LaTeX.

Q: For LaTeX, does anyone know of something equivalent to the Google Styleguides?

Quick searches of the web for LaTeX styleguides have returned plenty of styleguides emphasizing how compiled LaTeX documents should appear. I couldn't find anything emphasizing how the uncompiled .tex document should appear.

I suppose if there weren't anything equivalent to the Google Styleguides, a standard, very cleanly written and commented .tex template would suffice.

UPDATE: Over at StackOverflow, I've found a similar post asking about Ruby coding style guidelines. There are a number of helpful links provided there. I'm looking for something kind of similar.

Answer 1

The most general advice is: Use whitespace to make your code readable.

Let me give a few examples.

1. Always put \begin{environment} and \end{environment} on separate lines, without other content. An environment usually indicates that you are doing something "radically different", and it's easier to find the environment this way. Related:

2. Inside an environment, use indentation as you would in any programming language. Whether you use 2, 4 or some other number per nesting level doesn't matter much (but if your editor uses a proportional font you probably want at least 4; spaces are usually much smaller than printed characters in proportional fonts).

   \begin{equation}
     \det
     \begin{pmatrix}
       1 & 2 \\
       3 & 4
     \end{pmatrix}
     = -2
   \end{equation}
   

3. Whenever you force a line break with \\ (in a table, a matrix, an align-environment...), it goes without saying that it should be followed by a linebreak in the code.

4. In math mode, spaces are ignored. So use spaces around binary relations, and in some cases also binary operators. Write $a^2 + b^2 = c^2$ instead of $a^2+b^2=c^2$. Also spaces after commas as in $(x, y, z)$ is a good idea.

5. In environments such as align, blank lines are not allowed. But you can give yourself some vertical blank space by putting a single % on a line between the equations.

   \begin{align*}
     \sum_{n=1}^{\infty} \bigl(F(\tau^n m) - F(\tau^{n-1} m)\bigr)       &= x\\
   %
     \sum_{n=1}^{\infty} \bigl(F(\tau^{-n} m) - F(\tau^{-(n-1)} m)\bigr) &= y
   \end{align*}
   

6. The same trick applies in ordinary text if you don't want a paragraph break. But also remember that one blank line has the same effect as five blank lines; around \chapter and \section headings it can be a good idea to have several blank lines. This makes it easier to navigate.

Most of the above points have the effect of making your code look somewhat like the compiled document, which I find very nice. Of course, an editor with syntax-highlighting, indentation facilities and brace matching is also great help.

Answer 2

(This was originally a comment, but I think I need formatting to be clear.)

I can't answer your question, and I think even a community wiki post attempting to distill a guide would be a failure since, as Will says, styles vary a lot.

Two suggestions:

1. For anything even slightly complicated, put one command per line. For example, if you need to define a macro that say, ends the current paragraph, skips two lines, and then puts its argument in a framed box, write something like this.

   \def\foo#1{%
       \par
       \vskip2\baselineskip
       \fbox{#1}%
   }
   

   I sometimes violate this when multiple things logically belong together like in the example below.

2. Use indentation to show grouping just as you would in another programming language. It matter less how many spaces/tabs you use (although I personally find 1 or 2 to be too few, I know others disagree), than that you do it. The above code is an example. Another place is inside of a box like \vbox or when you use explicit grouping like \begingroup ... \endgroup.

   \begingroup
       \setbox0=\vbox{%
           \hsize=4in
           \parindent=0pt
           \hrule height.08em
           \kern.65ex
           \hfil\TeX\hfil
           \par
           \kern.4ex
           \hrule height.08em
       }%
       % other stuff
       \box0
   \endgroup
   

   I violated my first suggestion with the \hfil\TeX\hfil which seems easier to read when it is on a single line.

I find that following these two "rules" makes my own code reasonably easy to read.