Writing readable LaTeX

Most of what I say is covered by other answers, but I will write here my thoughts.

First of all, if you write a lot in LaTeX format, I think you should leave LyX and go for any plain text editor. In the (near) future you will be faster (reading and writing code).

About writing readable code. Here are some tips to make it readable:

  • One of the main features I found in LaTeX is the ability you have to write what you want. But don't fail at deciding what you want! I mean, in your code you (shouldn't want) don't want x to be bold (mathbf), you must want x to be a vector (\vec{x}). You will decide later what a vector looks like, but at first, you don't have to worry about it.
  • Next, if you usually define some sets you can define \set command (and later you will worry about how sets are displayed), but, as David Carlisle pointed, you can define shorter commands.
  • This is a must have in my documents: \R (\mathbb{R}) to define the real numbers. It is an entity so I define a command to call them. But I wouldn't define \Rn for \mathbb{R}^n, because then you aren't writing what you want, you are fastening your code input (which shouldn't be done that way).
  • May be \quad is not easy readable for you, but I think it will in the future.
  • This example is no so long, so you can't see how indenting your code benefits the reading of your code, but it really does.
  • I use \[,\] but I don't use \( and \) because I don't read math really good between those delimiters. So I changed them to $.
  • Personally, I don't write comments in my code unless I need to edit it later or something (I use comments as reminders). If you read code fast you don't need comments which explains what are you doing (in my case, they break my concentration).

This is how I would write your code:

\documentclass{article}
\usepackage{mathtools}
\usepackage{amsfonts}

\renewcommand\vec[1]{\mathbf{#1}}
\newcommand\set[1]{\mathcal{#1}}
\newcommand\R{\mathbb{R}}

\begin{document}
\subsection{Convex sets}
A set $\set{S}$ in $\R^n$ is said to be convex if 
\[
    \vec{x}_1, \vec{x}_2 \in \set{S} \implies \lambda \vec{x}_1 + (1-\lambda) \vec{x}_2 \in \set{S} \quad \text{for all } 0 < \lambda < 1 
\]
\end{document}

After that, I think you should differentiate writing code and fastening your input. Most of people defines commands to write faster (like \newcommand\vx{\vec x} from Niel de Beaudrap). I don't agree with that. To write faster you should use an editor (or a third party app) which lets you create snippets (i.e. I would make a snippet with \vec{x} which would be called when you type vx).

At last, to fasten your code-reading you must use a program which shows your code with colors (a color for math, a color for commands, a color for text,…). This is an example of my code (the theme and font I show here is not the usual, but I'm not in my main operating system, however I don't hate this setup): enter image description here

Summary

These are my ideas:

  1. Write what you want (but don't misunderstand what you really want). The commands you use have to be entities, not just 'shortcuts'. Later, you will care about how will it look like.
  2. Don't use commands as snippets (use a good editor or a third party app to make use of snippets).
  3. Indent your code.
  4. Use an editor which displays the code with different colors.
  5. Again, if you want your code to be readable don't use \mathbf{x} \in \mathbb{R}^n or \vx \in \Rn. I would go for \vec{x} \in \R^n.

There probably are editors that do the kind of textual substitution that you describe (emacs on your example already makes the section heading in a different font, although it doesn't hide the \subsection markup, it clearly could given sufficient lisp definitions).

Perhaps I'm just an old Luddite but I find the font changes in the editor distracting and certainly if the editor starts hiding markup it seems simpler for simple things but for anything more complicated, or if things start to go wrong it makes things a lot harder to understand as you are never sure if what you are seeing is what is actually being processed.

What can help is to give more semantically relevant names to the markup so that it reads more naturally. Here I think you are using calligraphic to denote sets, blackboard bold to denote the common number fields, and upright bold (I prefer bold math italic myself) to denote vectors. so after some simple definitions such as

\newcommand\sets{\mathcal}
\newcommand\R{\mathbb{R}}
\newcommand\V{\mathbf}

You could have a perhaps more readable source

\subsection{Convex sets}
A set \( \sets{S} \)
in \( \R^n \)
is said to be convex if 
\[ \V{x}_1, \V{x}_2 \in \sets{S} \implies \lambda \V{x}_1 +
(1-\lambda) \V{x}_2 \in \sets{S} \text{~~~for all~~~} 0 < \lambda < 1 \]

Of course, there are many variants, if you don't have too many sets you could define \S to be \mathcal{S} and use \S instead of \sets{S} or whatever you find most natural.


In addition to Davids answer, you can use unicode with Luatex to make the code more readable. I know that this is difficult to input, and therefore not suitable for everyone, but I wanted to show what is possible:

\documentclass{article}

\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{unicode-math}

\setmathfont{Asana Math}

\newcommand\set{\mathcal}
\renewcommand\vec{\mathbf}

\begin{document}

A set \( \set{S} \) in \( ℝ^n \) is said to be convex if 
\[ \vec{x}_1, \vec{x}_2 ∈ \set{S} ⇒ λ \vec{x}_1 + (1-λ) \vec{x}_2 ∈ \set{S} 
    \text{~~~for all~~~} 0 < λ < 1 \]
\end{document}

Edit: As pointed out, the boldface x is U+1D431 and the calligraphic S is U+1D4aE . You can then leave out the command definitions, and write:

A set \(  \) in \( ℝ^n \) is said to be convex if 
\[ _1, _2 ∈  ⇒ λ _1 + (1-λ) _2 ∈  
    \text{~~~for all~~~} 0 < λ < 1 \]