GNU Astronomy Utilities



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 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.


Footnotes

(298)

https://www.gnu.org/software/gsl/design/gsl-design.html#SEC15

(299)

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).

(300)

The convention to use underscores to separate words, called “snake case” (or “snake_case”). This is also recommended by the GNU coding standards.

(301)

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: (setq-default indent-tabs-mode nil)