Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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.

share|improve this question
1  
This would be a great idea! (Although I doubt you'll be able to find consensus for writing LaTeX code, as styles vary quite significantly.) –  Will Robertson Feb 27 '11 at 4:11
1  
@brianjd — Are you referring more to LaTeX documents or package code? –  Will Robertson Feb 27 '11 at 6:15
    
As Will knows, I have some ideas for formatting LaTeX3 code - see for example how siunitx is laid out (there are some updates, though, so also expect changes!) –  Joseph Wright Feb 27 '11 at 8:59
1  
Be aware that the Google style guides are meant for Google products, not as a general programming guidelines. Unfortunately they have become so popular that people on SO have to invest a lot of time to tell people not to apply them. –  Philipp Feb 27 '11 at 12:35
1  
@brianjd: No, I'm referring to (language-specific) general-purpose style guides vs. company-specific style guides. The Google style guides are only partially valid for non-Google software. I can't comment on the R style guide, but the C++ guide is often at odds with current best practices and experts' suggestions. –  Philipp Mar 1 '11 at 20:33
show 4 more comments

2 Answers 2

up vote 28 down vote accepted

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.

share|improve this answer
    
@Villemoes: your formatting issue was discussed on meta a while ago - you need to use four indent spaces per list level, so 8 for 'code inside a list' –  Joseph Wright Feb 27 '11 at 8:19
1  
@Villemoes: I've fixed it –  Joseph Wright Feb 27 '11 at 8:20
    
@Joseph: Odd. I didn't have any luck with that when I tried it for my answer. I ended up using pre and code HTML tags. –  TH. Feb 27 '11 at 8:22
    
The bit about extra space around \chapter or \section sounds good but it's editor dependant. For example I use AUCTeX which makes chapter and section titles use a larger font –  kahen Feb 27 '11 at 8:32
    
@TH. Well it 'worked for me' :-) Take a look at the code to see how I've laid it out. –  Joseph Wright Feb 27 '11 at 8:42
show 6 more comments

(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.

share|improve this answer
    
Thanks for the response. I just wanted to cross-apply my comment to Will's here: I think style varying a lot is PRECISELY the reason that a general style guideline should be adopted. –  lowndrul Feb 27 '11 at 16:03
add comment

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.