---

13.3 Coding conventions ¶

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.

• The code must be easy to read by eye. So when the order of several lines within a function does not matter (for example, when defining variables at the start of a function). You should put the lines in the order of increasing length and group the variables with similar types such that this half-pyramid of declarations becomes most visible. If the reader is interested, a simple search will show them the variable they are interested in. However, this visual aid greatly helps in general inspections of the code and help the reader get a grip of the function’s processing.
• A function that cannot be fully displayed (vertically) in your monitor is probably too long and may be more useful if it is broken up into multiple functions. 40 lines is usually a good reference. When the start and end of a function are clearly visible in one glance, the function is much more easier to understand. This is most important for low-level functions (which usually define a lot of variables). Low-level functions do most of the processing, they will also be the most interesting part of a program for an inquiring astronomer. This convention is less important for higher level functions that do not define too many variables and whose only purpose is to run the lower-level functions in a specific order and with checks.

  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 do not have to worry about decreasing the speed. By default Gnuastro will compile with the -O3 optimization flag.

• All Gnuastro hand-written text files (C source code, Texinfo documentation source, and version control commit messages) should normally be no more than 75 characters per line. Monitors today are certainly much wider, but with this limit, reading the functions becomes much more easier. Also for the developers, it allows multiple files (or multiple views of one file) to be displayed beside each other on wide monitors.

  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.

• The headers required by each source file (ending with .c) should be defined inside of it. All the headers a complete program needs should not be stacked in another header to include in all source files (for example main.h). Although most ‘professional’ programmers choose this single header method, Gnuastro is primarily written for professional/inquisitive astronomers (who are generally amateur programmers). The list of header files included provides valuable general information and helps the reader. main.h may only include the header file(s) that define types that the main program structure needs, see main.h in Program source. Those particular header files that are included in main.h can of course be ignored (not included) in separate source files.
• The headers should be classified (by an empty line) into separate groups:
  1. #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 does not use the GNU C library.
  2. The C library header files, for example, stdio.h, stdlib.h, or math.h.
  3. Installed library header files, including Gnuastro’s installed headers (for example cfitsio.h or gsl/gsl_rng.h, or gnuastro/fits.h).
  4. Gnuastro’s internal headers (that are not installed), for example gnuastro-internal/options.h.
  5. For programs, the main.h file (which is needed by the next group of headers).
  6. That particular program’s header files, for example, mkprof.h, or noisechisel.h.

  As much as order does not matter when you include the header of each group, sort them by length, as described above.

• All function names, variables, etc., should be in lower case. Macros and constant global enums should be in upper case.
• For the naming of exported header files, functions, variables, macros, and library functions, we adopt similar conventions to those used by the GNU Scientific Library (GSL)²⁹⁵. In particular, in order to avoid clashes with the names of functions and variables coming from other libraries the name-space ‘gal_’ is prefixed to them. GAL stands for GNU Astronomy Library.
• All installed header files should be in the lib/gnuastro directory (under the top Gnuastro source directory). After installation, they will be put in the $prefix/include/gnuastro directory (see Installation directory for $prefix). Therefore with this convention Gnuastro’s headers can be included in internal (to Gnuastro) and external (a library user) source files with the same line

  # 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 does not 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 redundant²⁹⁶.

• All installed functions and variables should also include the base-name of the file in which they are defined as prefix, using underscores to separate words²⁹⁷. The same applies to exported macros, but in upper case. For example, in Gnuastro’s top source directory, the prototype of function gal_box_border_from_center is in lib/gnuastro/box.h, and the macro GAL_POLYGON_MAX_CORNERS is defined in lib/gnuastro/polygon.h.

  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.

• There should be no trailing white space in a line. To do this automatically every time you save a file in Emacs, add the following line to your ~/.emacs file.

  (add-hook 'before-save-hook 'delete-trailing-whitespace)
  

• There should be no tabs in the indentation²⁹⁸.
• Individual, contextually similar, functions in a source file are separated by 5 blank lines to be easily seen to be related in a group when parsing the source code by eye. In Emacs you can use CTRL-u 5 CTRL-o.
• One group of contextually similar functions in a source file is separated from another with 20 blank lines. In Emacs you can use CTRL-u 20 CTRL-o. Each group of functions has short descriptive title of the functions in that group. This title is surrounded by asterisks (*) to make it clearly distinguishable. Such contextual grouping and clear title are very important for easily understanding the code.
• Always read the comments before the patch of code under it. Similarly, try to add as many comments as you can regarding every patch of code. Effectively, we want someone to get a good feeling of the steps, without having to read the C code and only by reading the comments. This follows similar principles as Literate programming.

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 Gnuastro manifesto: 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 web page 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: Official manual At https://www.gnu.org/software/emacs/manual/emacs.html. This is a great and very complete manual which is being improved for over 30 years and is the best starting point to learn it. It just requires a little patience and practice, but rest assured that you will be rewarded. If you install Emacs, you also have access to this manual on the command-line with the following command (see Info). $ info emacs A guided tour of emacs At https://www.gnu.org/software/emacs/tour/. A short visual tour of Emacs, officially maintained by the Emacs developers. Unofficial mini-manual At https://tuhdo.github.io/emacs-tutor.html. A shorter manual which contains nice animated images of using Emacs.