[Reproduce-devel] [task #15320] Revising the *Commit Message* section of README-hacking.md

[Mohammad Akhlaghi]

Follow-up Comment #1, task #15320 (project reproduce):

Thanks for raising this point Mohammadreza,

About the mandatory point, the thing you should consider is that in a Free or
Open Source Software, the source code itself must be easily readable, like a
book. 

Imagine a multi-author book/paper. Is one paragraph written in one font size,
line width, or line spacing (which is the subjective choice of its author),
while the next paragraph has different typographical settings because another
author wrote it? Will such a book be easily readable by a third person? Won't
these different styles discourage group work? 

Because of this, in free software projects, there are usually standards to
follow for the style of the code. For example, in the GNU Coding Standards,
there is a whole section
<https://www.gnu.org/prep/standards/html_node/Formatting.html> on "Formatting
your source code". If you look on the first line it says: "Please keep the
length of source lines to 79 characters or less", and following that it is
suggested stylistic/subjective formatting patterns in the code that have no
effect on the compiling/running of the program. They are just defined because
once everyone follows them, the code will be readable/welcome by others.

Another nice example is Python's PEP8 style guide
<https://www.python.org/dev/peps/pep-0008/>. Have a look at the contents and
types of recommendations to see what I mean. In many cases, people will even
not consider looking into a Python code if it doesn't follow these styles
(since it slows them down, and it shows the person didn't care about sharing
the code with others to read).

If you inspect any professional project that involves more than one person,
you will see similar style guides. For example see the LSST C++ Style Guide
<https://developer.lsst.io/cpp/style.html> (for the data analysis software of
the Large Synoptic Survey Telescope, that will start operations soon), in
particular note all the "SHOULD"s and "MUST"s.

On the second point of providing a description of why something has been set.
Of course! If you feel the reason behind something is not clear, please post
it here so we add some explanation. 

Hopefully later when we write a full manual, we'll have more space for this.
But there is also Gnuastro's Coding conventions
<https://www.gnu.org/software/gnuastro/manual/html_node/Coding-conventions.html>
that give a little more detail.

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/task/?15320>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/