This is a list of comments on some stylistic issues for master theses
and similar documents that I am supposed to examinate.
Most of these were compiled from a collection of frequently encountered stylistic errors
in previous master theses.
My suggestions are based on scientific writing conventions used
by international publishers.
Most of these points concern both English and Swedish.
As a general reference for proper writing in English, I recommend
Heffernan, Lincoln, Atwill: Writing, A College Handbook. 5th ed., Norton, 2001
or similar books.
For exjobb theses in Swedish there exist additional suggestions on technical writing, such as the Lathund för rapportskrivning.
[New in 2011]
I do no longer allow citing (and thus using material from)
Wikipedia and other public web lexica in final thesis reports.
Such material is not generally trustworthy.
For instance, I recently traced an error made in an exam by several students
back to an erroneous article in such a web lexicon.
Wikipedia may still be useful as a starting (!) point for a first recherche
about a subject, but you should read and cite the original articles mentioned
there (and of course also others that are not mentioned by that article's authors).
Examples: "We have shown in previous work [3,4] that..." - "We will see that..." - "Let us consider now ..."
If you want to mark something as your own personal opinion or experience,
you should speak of yourself in the third person:
"The author thinks that ..."
Never use "you" to directly address the reader, and never command the user
by using imperative form. Also here the third
person is appropriate to create the necessary distance:
"The reader may have noticed that ..." -
"We refer the interested reader to ..."
The reason that I do not follow this rule in this document itself is that this document is not a thesis and not a scientific paper, and that I most probably know the reader of this document personally.
Hence, choose a descriptive title without abbreviations, even if the title becomes a bit longer.
Positive example: Parallelization of the interpreter in a test system for mobile telecommunication components
In your own interest, I am fussy about orthography, grammar, and consistency of terminology, and I will reject a thesis with more than 15 typos on a page.
Please use a spell checker and, if possible, ask someone else (not your opponent) to proofread your thesis before you hand it in to me.
"It was shown that this problem is NP-complete."
If you use active tense instead, you will be forced to give the author:
"Cook [23] has shown that this problem is NP-complete."
An additional clustering of the chapters into multiple parts may be suitable for textbooks with more than 400 pages, but never for a thesis.
Sections and subsections are usually numbered up to a nesting
depth of 3 or 4.
Hence, "Section 3.1.4" looks still fine, while "Section 3.1.5.1.2.1.1"
does not.
LaTeX automatically enforces this standard.
Avoid phrases that do not really add information. Keep the quality and precision of the presentation but minimize the length.
Bad example: Just this.
This rule applies also to enumerations. Hence, avoid incomplete sentences as in
Memory types:
* Data memory. Contains...
* Program memory. Is ...
instead, you should write
The memory types are the following:
* Data memory. The data memory contains...
* Program memory. The program memory is ...
Hence, choose a few very central abbreviations that you want to keep, introduce them with their full name properly before their first use, and spell out the others.
Long listings in verbatim mode (typewriter font)
are hard to read.
I recommend to use the available stylistic features to structure
program code, such as boldface font for key words, italics for variable and
function names, slanted for comments, etc.
Avoid long names for variables
and constants, especially if you need to reference them in mathematical formulas.
Avoid excessively long algorithms or program listings. Partition the algorithm into suitable parts and package the parts into figures.
If you present an algorithm that you invented,
"see Figure 3 for ..." - "as shown in Section 2.3"
Here, "Figure 3" is a proper name and thus the first character is capitalized.
but:
"see the third figure ..." - "see the previous section"
Here, "figure" is an ordinary noun.
Note that numeric citations are to be treated as comments (like footnote superscripts), not as independent text objects. I also recommend to add some text that simplifies reading without looking up the corresponding bibitem in the bibliography.
Hence, you may write
"Applying Brent's theorem [7] yields ..." or "see Cormen et al. [4]"
but not
"[7] yields ..." nor "see [4]"
as [7] by itself is just an optional comment, not a subject.
A minor issue is that multiple numeric references should appear in order, that is, [3,4] instead of [4,3].
Long flat lists of references are not a good citation style.
For instance,
"A lot of loop transformations have been developed to increase data locality,
for example [3], [5], [6], [7], [10], [11], [12], [13], [16], [17], [20], [21], [22]."
Instead, more effort should be put in reviewing and structuring the related work,
even if this needs more time and space:
"Many loop transformations have been proposed in the literature of the last
two decades. For instance, Kennedy et al. [10] give an in-depth treatment
of loop interchange. Tiling of multidimensional loops is discussed in
a seminal paper by Wolf and Lam [21].
Polychronopoulos [13] proposes cycle shrinking for
loops with dependence cycles of static distances larger than one.
Banerjee [5,6] gives an introduction to the theory of unimodular transformations.
Ancourt and Irigoin [3] introduce the polytope model for the representation
of index spaces, which is used in
subsequent work by Lengauer [16], Xue [22], ... . See also Wolfe's textbook
[20] for a comprehensive overview."
Please note also that there should be a blank space before each citation reference symbol, such as here [47] (in the LaTeX source: before each \cite{} command).
Avoid web documents, give preference to printed books and articles.
Note that web documents are (with very few exceptions)
highly volatile, subject to dynamic update without
notice, and generally unrefereed;
hence they are much less trustworthy
than printed publications, which underwent a thorough reviewing process
and can thus regarded as correct and original work (also with very few exceptions).
Experience shows that, on the average, more than 50% of all URLs cited
do no longer exist after 2 years. A printed book or journal article
exists forever.
For each (non-web) bibitem, give the author, title, year and the publisher. The ISBN is optional. This is standard for scientific writing. Note that I override here the IDA guidelines.
For articles, give also journal name, volume, issue, and page numbers.
For papers in conference proceedings, give the conference name and
the page numbers.
If you cannot avoid citing a web document (such as online documentation), give the author, the year, and the location of the project (e.g., university or research institute).
By the way, the publisher information tells the experienced reader a lot about the value of a book publication (and thus, whether it is worth the effort to get access to it). For instance, "Morgan Kaufmann" or "Springer" books are usually regarded as high quality publications.