[Tex/LaTex] What are coding conventions in LaTeX

best practicessourcecode

What do I mean by Convention?

First of all, allow me to clear myself about the word 'conventions.

As most of you already know, coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices and methods for each aspect of a piece program written in this language [from WikipediA]. These conventions usually cover 'file organization', 'indentation', 'comments', 'declarations', 'statements', 'white space', 'naming conventions', 'programming practices', 'programming principles', 'programming rules of thumb', etc.

An Example!

As an example, consider Java (and other C-like programming languages). In Java Naming Conventions, class names should be in UpperCamelCase, methods and variables should follow lowerCamelCase and constants should be ALLCAPS.

A Personal Experience:

There are some of these conventions that I have realised while writing smaller reports. For example, the second time I wrote a report with LaTeX, I realized it's better to put each chapter in a separate file. Also, I learned about them reading other peoples code like this one that I learned about it recently: One-Sentence-per-Line. This looks very important for sake of readability of the latex source but I never thought about it until I read that answer.

Here comes the Question!

I'm about to write my master thesis and I want to know these conventions for LaTeX. My goal is to achieve a readable, reusable, easy to modify and standard source code.

If you know any conventions, or if you have your own personal ones, regarding any aspect of LaTeX, please share with me and I would be delighted if you support your answers/conventions with reasons or examples.

Best Answer

I'm about to write my master thesis and I want to know these conventions for latex. My goal is to achieve a readable, reusable, easy to modify and standard source code.

I am afraid I cannot offer any advice on the "easy to modify" and "standard source code" parts as they are contradicting the very essence of TeX and LaTeX2e. Your question sounds as if you have been influenced by some High Priest of Coding. Beware as their favorites, code and teachings change.

First let us distinguish between writing your thesis and programming LaTeX macros. I have a friend who is a painter and is one of the most untidy persons on the universe, but out of his workshop come out the most beautiful paintings. My late Supervisor's office and his desk was buried in books, papers and even old pizza boxes, but he wrote beautiful maths. Both the Professor and the artist had exceptional sharp and focus minds. Your purpose I guess is to write your thesis and get your Masters.

Organize yourself with a good distribution, set up a git or other version control system and perhaps a dropbox account, I recommend you organize your folders as follows (works for me),

    mythesis |
             - chapter01
                   - notes
             - chapter02
             - chapter-nn
             - graphics
             - plots
                  - data
             - any specials
             - delete
             bibliography files etc
             main


   mythesis-versions
             thesis-01.zip
             thesis-02.zip
             thesis-03.zip

Split the write-up from the coding. When I am writing, I don't want any distractions. It doesn't matter if the code is beautiful or not, if the text is ungrammatical or has spelling mistakes. I write quickly and focus on conveying my ideas or structuring code to work. This way I achieve "flow" much more easier. I am at my best when I do this on paper than computer. Find what works for you. In less productive hours I tidy up the code or do rewrites.

To make your code re-usable both for your older self as well as colleagues, means you need to package it and document it using literate programming, i.e, create a .dtx.

If you use re going to use LaTeX3 follow the conventions recommended by the LaTeX3 Team, is the closest thing to a standard. However, if you find yourself dealing with mostly LaTeX2e code, the following are some suggestions:

Use a suffix¹ to namespace rather that a prefix in internal macros. It makes LaTeX2e code more readable, i.e.,

   myfancysection@mex

rather than

   @mex@my@fancy@section

LaTeX3 code cannot be very readable by design so stick with conventions on prefixing etc.

   g_mex_my_fancy_section

Normally author interfaces have the convention of UpperCamelCasing, break the rule if possible. It is more difficult to type

   MyFancySection

rather

   myfancysection

and I personally find the latter as readable if not easier to read than the former. The Germans do this with their language all the time.

I would make an exception and any settings commands can be uppercased.

 DeclareDocumentFont and not declareDocumentFont or declaredocumentfont

Consistency is good for example the biblatex author created commands that are easy to remember and indicate their purpose well.

  textcite[][]{}
  Textcite

Took me about an hour to find out what was wrong with:

  setpgfkeys

where I should have typed

  setpgfqkeys

I couldn't see the difference. Choose your naming scheme carefully as it is a User Interface. Use a key value interface where possible.

Just to throw the spanner in the works, the most clean and readable code, which it almost seems as if it was organized with beauty in mind is that of ConTeXt. Unfortunately I don't use it that much.

There are a lot of QA on this site around the topic, search around and pick what you think will work for you.

NOTE:

[1] On suffixes: (it also appears that natural language evolution tends to add suffixes. "der Kommunis mus" (communism); "der Naturalis mus" (naturalism); "der Touris mus" (tourism). I guess one's background in coding and mother language impact on readability opinions. As noted earlier all are personal opinions. Perhaps a linguist can shed a bit more light here.

Related Solutions

[Tex/LaTex] Styleguide for LaTeX similar to the Google styleguides

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

Let me give a few examples.

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:
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}
```
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.
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.

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*}

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.

[Tex/LaTex] Naming LaTeX files: best practice

It depends a little if this files are only used by you are if you are planning to share them with other people, e.g. if you work with them on one document or the files are part of a LaTeX package.

But in general I would strongly recommend you to limit yourself to lowercase alphanumeric ASCII characters, i.e. a-z, 0-9 and -.

The reasons for that are:

Unicode or other non-ASCII characters can cause trouble when copied on a different file system with a different code page. I had the case that I couldn't even see files with German umlauts on a Windows share mounted by Linux. This is now much better, but still a risk. The normal TeX doesn't like non-ASCII character that much either.
Some file systems (FS) are case sensitive (e.g. under *nix FSs) others aren't (e.g. FAT, NTFS). If you keep you file names all lowercase you avoid collisions between files which can lead to loss of data when copied from a case sensitive to a case insensitive FS. Also you will run intro trouble on case sensitive systems when the actual filename has a different capitalization as on the hard drive. You might not realize that on e.g. Windows, but it will hit you then hard on a different FS.
Characters which are special in TeX will work as long they are valid at this position which excludes % and #. Others as & can cause trouble as well and there is no real reason to use them, so avoid them. Even _ which is commonly used and will work inside \input can cause trouble when the filename should be printed, so avoid it as well.
Spaces are "evil" in filename as well because some external tools will take them as file name separator. TeX should be fine with them, except when they used multiple times in a row. TeX will then combine them to one prior to the interpretation as a filename!
Dots will confuse the simple extension extraction algorithms used by LaTeX. See this question for an example.

I'm going through some effort in the svn-multi package to allow for arbitrary file names. This is done using verbatim mode which doesn't help for other input macros like \input, \include or \includegraphics.