Software code or another form of a document is considered to be a result of the creative work of software developers. However, in many agile methodologies documentation is assumed to be overwhelming overhead. Programmers are to write code, one can assume. And that is true to some extent. It is claimed that the best code documentation is a suite of tests that passes automatically on each build. This actually, is also a code.
Despite the fact, even the most orthodox software developers put a few lines of unstructured text into the product. Comments are inserted into the code to explain the logic behind the proposed solution. What the code is doing could be understood by analyzing the structure. Comments are essential to learning why the given code is written:
/*
* This variable is used privately to keep track of whether or not
* reboot_type is still set to its default value (i.e., reboot= hasn't
* been set on the command line). This is needed so that we can
* suppress DMI scanning for reboot quirks. Without it, it's
* impossible to override a faulty reboot quirk without recompiling.
*/
int reboot_default = 1;
source: kernel/reboot.c (Linux repository)
The same could be applied to the comments inserted into the repository as a part of the committing process. Although the structure of the comment is important it must provide meaningful information to the reader.
In GIT each commit is described within the commit message. There are many hints and golden rules created to help create the messages more useful. Most of the guidelines are addressing the issues of the text structure (indentation, white spaces). The quality of the content is way harder to be enclosed in the set of hints. Commit message is well described and illustrated in the original GIT source code documentation:
[[meaningful-message]]
The body should provide a meaningful commit message, which:
. explains the problem the change tries to solve, i.e. what is wrong
with the current code without the change.
. justifies the way the change solves the problem, i.e. why the result with the change is better.
. alternate solutions considered but discarded, if any.
source: Documentation/SubmittingPatches (GIT repository)
In other words, the message is to describe what and why instead of how the solution is provided. It explains the context of the change that has been put into the source code. Checking the compliance of the message with the formatting rules can be automated. Humans used to perform a checking if the message is meaningful in the process of the commit integration.
https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
https://www.theserverside.com/video/Follow-these-git-commit-message-guidelines
https://who-t.blogspot.com/2009/12/on-commit-messages.html