Formatting ugly code

Question

While I'm often happy with my output PDF result, my latex code often gets very ugly. Poor code readability makes the editing process very difficult. Are there any simple tricks to format my code to make it more readable?

Here's an example:

    \begin{align*}
    H_3\ket{\psi(t)} &= \left(\hbar\epsilon \int_{z_0}^{z_0+l}E_a^{(-)} E_a^{(+)} E_b^{(-)} E_b^{(+)} dz \right) \ket{\psi(t)} \\
    &= \underbrace{\left(\hbar\epsilon \int_{z_0}^{z_0+l}E_a^{(-)} E_a^{(+)} E_b^{(-)} E_b^{(+)} dz \right)}_{\text{equation \ref{H3}}} \underbrace{\left( \sum_n \sum_m c_{nm}(t) e^{-2 \pi i(n+m)c t/L} \ket{1_n}_a\ket{1_m}_b \right)}_{\ket{\psi(t)}} \\
    \end{align*}

How would you clean this up? Personally, I'm interested in adding new lines to make the individual lines more readable. But by indenting or splitting my code out into different lines I get error messages.

Newline characters should be ok, just don't add blank lines. You can use lone % characters instead of blank lines, too. — Mike Renfro, May 14 '16 at 02:18
Have you seen latexindent? Have a look for code sniffer on this site? — cmhughes, May 14 '16 at 07:14
I think this question may be a repeat. http://tex.stackexchange.com/q/95687/90087 and http://tex.stackexchange.com/q/12171/90087 although I think it is a good question and I would love to see a complete global, historical answer to it. — A Feldman, May 14 '16 at 14:13

score 7 · Accepted Answer · answered May 14 '16 at 05:09

Not really a trick, but I usually put long equations over several lines and indent layers of code systematically with 2 spaces for readability.

Just ensure that there are no blank lines in align environments, otherwise you will get the error ! Paragraph ended before \align* was complete..

For instance, I match the indentation for \left \right pairs and \int dz pairs when the equations are long:

\documentclass[a4paper,11pt]{article}

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{braket}

\begin{document}

\begin{align*}
  H_3 \ket{\psi(t)}
%%%%
  &= \left(
       \hbar\epsilon
       \int_{z_0}^{z_0+l}
         E_a^{(-)} E_a^{(+)} E_b^{(-)} E_b^{(+)}
       dz
     \right)
     \ket{\psi(t)} \\
%%%%
  &= \underbrace{
       \left(
         \hbar\epsilon
         \int_{z_0}^{z_0+l}
           E_a^{(-)} E_a^{(+)} E_b^{(-)} E_b^{(+)}
         dz
       \right)
     }_{\text{equation \ref{H3}}}
     \underbrace{
       \left(
         \sum_n \sum_m
           c_{nm}(t)
           e^{-2 \pi i(n+m)c t/L}
           \ket{1_n}_a \ket{1_m}_b
       \right)
     }_{\ket{\psi(t)}} \\
\end{align*}

\end{document}

The extra %%%% helps me locate the equals signs.

score 4 · Answer 2 · edited Apr 13 '17 at 12:35

One thing that complicates your code is a lot of expressions of the form ^{(…)}. I define a shortcut for them using the following code:

\catcode`\"=13
\newcommand*{"}[1]{^{(#1)}}

This means a"1 becomes a⁽¹⁾ and a"{10} becomes a⁽¹⁰⁾.

I would also define macros for sections of code you use frequently (e.g. you already have \ket, which is great). For example, you can try

\newcommand{\paren}[1]{\left(#1\right)}

(or use \DeclarePairedDelimiter).

Another quantity you use more than once (possibly also in the rest of the document) is the integral, so let's wrap it in a macro:

\newcommand{\Eabint}{\int_{z_0}^{z_0+l} E_a"- E_a"+ E_b"- E_b"+ dz}

The final thing I noticed is that the \underbrace commands are making the code harder to read/more cluttered. You can put them on their own lines as long as there are no blank lines.

After making all these changes, the code looks a lot less messy:

\begin{align*}
H_3\ket{\psi(t)} &= \paren{\hbar\epsilon \Eabint} \ket{\psi(t)} \\
&= \underbrace{
     \paren{\hbar\epsilon \Eabint}
   }_{\text{equation \ref{H3}}}
   \underbrace{
     \paren{\sum_n \sum_m c_{nm}(t) e^{-2 \pi i(n+m)c t/L} \ket{1_n}_a\ket{1_m}_b}
   }_{\ket{\psi(t)}} \\
\end{align*}

Formatting ugly code

2 Answers2