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 suffix1 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.
It's very commendable trying to get accents right. A person's name should always be spelled in the original way, if the alphabet is the same. For original names using a different script, any internationally recognized transliteration system can be used.
It's sometimes hard to realize that Chebychev, Chebysheff, Chebyshov, Tchebychev, Tchebycheff, Tschebyschev or Tschebyscheff is one and the same person, that is Pafnuty Chebyshev (in a widely used transliteration system) or Pafnutij Čebyšev (in another system). (In Russian, with cyrillic alphabet, the name is Пафнутий Чебышев.)
Writing "Poincare", "Cech" or "Erdos" is quite common, but wrong. And it's not difficult to use the correct spellings: "Poincaré", "Čech" and "Erdős". (Correctly pronouncing the names is another matter.)
For your problem of not remembering the accents, using macros can be a solution. Note how I solve the "étale–étalé" problem with a *-variant.
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{xspace}
\newcommand{\Poincare}{Poincar\'e\xspace}
\newcommand{\adele}{ad\`ele\xspace}
\newcommand{\Cech}{\v{C}ech\xspace}
\newcommand{\Erdos}{Erd\H{o}s\xspace}
\makeatletter
\newcommand{\etale}{\'etal\@ifstar{\'e}{e\xspace}}
\makeatother
\begin{document}
\Poincare and \Erdos went to an \etale* party at \Cech's
with an \adele and an \etale as gifts. \Cech was happy.
Poincaré and Erdős went to an étalé party at Čech's
with an adèle and an étale as gifts. Čech was happy.
\end{document}
Best Answer
There was a talk at TUG'11 exactly about this: Didier Verna, Toward LaTeX coding standards:
The paper is available for TUG members only till the end of the year, but the video is available for all. Take a look: Didier has many interesting thoughts to offer. You might be also interested in Chris Rowley's talk at TUG'09. And please consider joining TUG: this gives you an immediate access to TUGboat papers and many other benefits (see http://tug.org/join.html)