3.8 Documentation
In the column function, h_shaft is the shaft’s height, r_base_shaft is the shaft’s base radius, h_echinus is the echinus’ height, r_base_echinus is the echinus’s base radius, h_abacus is the abacus’ height and, finally, l_abacus is the abacus’ length. Because the function already employs many parameters and its meaning may not be clear to someone that reads the function’s definition for the first time, it is convenient to document the function. For that, Julia provides two different features. The first one is the character #: each time the character # is used, Julia will ignore everything that is in front of it until the end of the line. That allows text to be written in the code without Julia trying to interpret its meaning. The second one is the concept of documentation string: a string that appears immediately before a function definition is treated as the documentation of that function.
Using documentation, the program for creating Doric columns will look something like what is shown below. This example shows the different ways documentation can be used in Julia. Actually, the program is so simple that it should not require so much documentation.
# Drawing Doric Columns
# The drawing of a Doric column is divided into three parts:
# shaft, echinus and abacus. Each of these parts has an
# independent function.
"
Draws the shaft of a Doric column.
p: column's center base coordinate,
h-shaft: shaft's height,
r-base: shaft's base radius,
r-top: shaft's top radius.
"
shaft(p, h_shaft, r_base, r_top) =
polygon(p+vxy(-r_top, h_shaft),
p+vxy(-r_base, 0),
p+vxy(+r_base, 0),
p+vxy(+r_top, h_shaft))
"
Draws the echinus of a Doric column.
p: echinus' center base coordinate,
h-echinus: echinus' height,
r-base: echinus' base radius,
r-top: echinus' top radius.
"
echinus(p, h_echinus, r_base, r_top) =
polygon(p+vxy(-r_base, 0),
p+vxy(-r_top, h_echinus),
p+vxy(+r_top, h_echinus),
p+vxy(+r_base, 0))
"
Draws the abacus of a Doric column.
p: abacus' center base coordinate,
h-abacus: abacus' height,
l-abacus: abacus' length.
"
abacus(p, h_abacus, l_abacus) =
rectangle(p+vxy(-(l_abacus/2), 0), p+vxy(l_abacus/2, h_abacus))
"
Draws a Doric column composed of a shaft, an echinus and an abacus.
p: column's center base coordinate,
h-shaft: shaft's height,
r-base-shaft: shaft's base radius,
h-echinus: echinus' height,
r-base-echinus: echinus' base radius = shaft's top radius,
h-abacus: abacus' height,
l-abacus: abacus' length = 2*echinus top radius.
"
column(p, h_shaft, r_base_shaft, h_echinus, r_base_echinus, h_abacus, l_abacus) =
begin
# We draw the shaft at the base point p
shaft(p, h_shaft, r_base_shaft, r_base_echinus)
# We place the echinus on top of the shaft
echinus(p+vxy(0, h_shaft), h_echinus, r_base_echinus, l_abacus/2)
# and the abacus on top of the echinus
abacus(p+vxy(0, h_shaft+h_echinus), h_abacus, l_abacus)
end
When a program is documented, it is easier to understand what the program does, without having to study the functions’ body. Although it is important to document our programs, it is also important to note that excessive documentation can also have disadvantages. To avoid them, the following ideas should be taken into consideration:
The code in Julia should be clear enough for a human being to understand. It is better to spend more time writing clearer code than to write documentation explaining it;
Having documentation that does not correspond to the program is worse than having no documentation at all;
Frequently, we need to modify our programs in order to adapt them to different purposes. The more documentation we have, the more documentation we will have to modify to make it coherent with the changes made to the program.
For these reasons, we should try to write the code as clear as possible and, at the same time, provide short and useful documentation: the documentation should not say what is already obvious from reading the program.
3.8.1 Exercises 15
3.8.1.1 Question 44
Consider an arrow with an origin in \(P\), a length of \(\rho\), an inclination \(\alpha\), an opening angle \(\beta\) and an arrowhead size \(\sigma\) as shown in the following figure:
Define a function arrow that, given the parameters \(P\), \(\rho\), \(\alpha\), \(\beta\), and \(\sigma\), creates the corresponding arrow.
3.8.1.2 Question 45
Using the function arrow, define a new function called arrow_from_to that, given two points, creates an arrow that goes from the first point to the second. The arrowhead should have a \(\sigma\) size of one unit and an angle \(\beta\) of \(\frac{\pi}{8}\).