Maneage - Tasks: task #15320, Revising the *Commit Message*...
You are not allowed to post comments on this tracker with your current authentication level.
task #15320: Revising the *Commit Message* section of README-hacking.md
Submitter: | Mohammadreza Khellat <mkhellat> | ||
Submitted: | Mon 08 Jul 2019 04:36:39 AM UTC | ||
Should Start On: | Mon 08 Jul 2019 12:00:00 AM UTC | Should be Finished on: | Mon 08 Jul 2019 12:00:00 AM UTC |
Category: | None | Priority: | 7 - High |
Status: | In Progress | Privacy: | Public |
Percent Complete: | 0% | Assigned to: | None |
Open/Closed: | Open | Effort: | 0.00 |
Fri 19 Jul 2019 04:55:39 PM UTC, comment #1: |
Mohammad Akhlaghi <makhlaghi>![]() |
Mon 08 Jul 2019 04:36:39 AM UTC, original submission:
Follwoing some discussions around mandatory and low-level requirements in task #15262: Source code downloads and Job manager, I am suggesting a revision of the Commit Message section of README-hacking.md.
|
Mohammadreza Khellat <mkhellat>![]() |
No files currently attached
Depends on the following items: None found
Items that depend on this one: None found
Carbon-Copy List
There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.
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 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. 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 (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 that give a little more detail.