In Gnuastro, we try our best to follow the GNU coding standards. Added to those, Gnuastro defines the following conventions. It is very important for readability that the whole package follows the same convention.
In general you can be very liberal in breaking up the functions into smaller parts, the GNU Compiler Collection (GCC) will automatically compile the functions as inline functions when the optimizations are turned on. So you don’t have to worry about decreasing the speed. By default Gnuastro will compile with the -O3 optimization flag.
Emacs’s buffers are excellent for this capability, setting a buffer width
of 80 with ‘C-u 80 C-x 3’ will allow you to view and work on several
files or different parts of one file using the wide monitors common
today. Emacs buffers can also be used as a shell prompt and compile the
program (with M-x compile), and 80 characters is the default width in
most terminal emulators. If you use Emacs, Gnuastro sets the 75 character
fill-column variable automatically for you, see cartouche below.
For long comments you can use press Alt-q in Emacs to separate them
into separate lines automatically. For long literal strings, you can use
the fact that in C, two strings immediately after each other are
concatenated, for example
"The first part, " "and the second part.".
Note the space character in the end of the first part. Since they are now
separated, you can easily break a long literal string into several lines
and adhere to the maximum 75 character line length policy.
#include <config.h>: This must be the first code line (not commented or blank) in each source file within Gnuastro. It sets macros that the GNU Portability Library (Gnulib) will use for a unified environment (GNU C Library), even when the user is building on a system that doesn’t use the GNU C library.
As much as order does not matter when you include the header of each group, sort them by length, as described above.
enums should be in upper case.
gal_’ is prefixed to them. GAL stands for GNU Astronomy Library.
# include <gnuastro/headername.h>
Note that the GSL convention for header file names is
gsl_specialname.h, so your include directive for a GSL header must
be something like
#include <gsl/gsl_specialname.h>. Gnuastro doesn’t
follow this GSL guideline because of the repeated
gsl in the include
directive. It can be confusing and cause bugs for beginners. All Gnuastro
(and GSL) headers must be located within a unique directory and will not be
mixed with other headers. Therefore the ‘gsl_’ prefix to the header
file names is redundant207.
gal_box_border_from_centeris in lib/gnuastro/box.h, and the macro
GAL_POLYGON_MAX_CORNERSis defined in
This is necessary to give any user (who is not familiar with the library structure) the ability to follow the code. This convention does make the function names longer (a little harder to write), but the extra documentation it provides plays an important role in Gnuastro and is worth the cost.
(add-hook 'before-save-hook 'delete-trailing-whitespace)
The last two conventions are not common and might benefit from a short discussion here. With a good experience in advanced text editor operations, the last two are redundant for a professional developer. However, recall that Gnuastro aspires to be friendly to unfamiliar, and inexperienced (in programming) eyes. In other words, as discussed in Science and its tools, we want the code to appear welcoming to someone who is completely new to coding (and text editors) and only has a scientific curiosity.
Newcomers to coding and development, who are curious enough to venture into the code, will probably not be using (or have any knowledge of) advanced text editors. They will see the raw code in the webpage or on a simple text editor (like Gedit) as plain text. Trying to learn and understand a file with dense functions that are all spaced with one or two blank lines can be very taunting for a newcomer. But when they scroll through the file and see clear titles and meaningful spaces for similar functions, we are helping them find and focus on the part they are most interested in sooner and easier.
GNU Emacs, the recommended text editor: GNU Emacs is an extensible and easily customizable text editor which many programmers rely on for developing due to its countless features. Among them, it allows specification of certain settings that are applied to a single file or to all files in a directory and its sub-directories. In order to harmonize code coming from different contributors, Gnuastro comes with a .dir-locals.el file which automatically configures Emacs to satisfy most of the coding conventions above when you are using it within Gnuastro’s directories. Thus, Emacs users can readily start hacking into Gnuastro. If you are new to developing, we strongly recommend this editor. Emacs was the first project released by GNU and is still one of its flagship projects. Some resources can be found at:
For GSL, this prefix has an internal technical application: GSL’s architecture mixes installed and not-installed headers in the same directory. This prefix is used to identify their installation status. Therefore this filename prefix in GSL a technical internal issue (for developers, not users).
The convention to use underscores to separate words, called “snake case” (or “snake_case”). This is also recommended by the GNU coding standards.
If you use Emacs,
Gnuastro’s .dir-locals.el file will automatically never use tabs for
indentation. To make this a default in all your Emacs sessions, you can add
the following line to your ~/.emacs file: