Are there best practices for committing commits and writing comments in these commits , for better communication and understanding during the software development process?
What would be best practices for commits in Git?
21
asked by anonymous 30.04.2015 / 02:17
2 answers
18
Commit granularity
As I've already replied here , the main good practice is to try to commit one feature at a time, regardless of whether you changed one or 10 files. That way you could reverse a change in case of problems, which is not as rare as you think.
Note that changing many files at the same time is a symptom that you could split the change into parts.
Comments
I'm not in favor of big explanations in commits comments.
What I recommend is a high-level explanation of at most one line of what was done, such as a mental note, from which the developer can remember or at least look for the specification of that change.
Content of the comment
Something used in almost every business that takes the process seriously, be it agile or traditional, is to link each commit to a ticket or issue of some system like the Jira, Mantis or Bugzilla.
Each ticket is, in turn, linked to a specific task or an entire user story, depending also on the granularity in which the project is planned.
Thus, the developer can easily consult the documentation and possible discussion about the bug or functionality. It is also possible to track in the version management system what changes were necessary to implement the X functionality.
Tool Help
Most IDEs have integration with the tickets tools and, properly configured, are able to automatically add the ticket / em> where the developer is working.
You can also configure a rule in the versioning system to prevent commits from being made without comments and without linking to a ticket .
In general, I do not recommend such a level of control, but it is something common in large companies to prevent inexperienced developers from doing commits .
05.05.2015 / 17:28
17
A " official "documentation 1 git has a recommendation on commits and messages. They are a set of good practices to make snowing by the story of the project easier to assimilate.
Though not mandatory, they are widely applied and replicated over the internet:
Check whitespace problems in code
This is easy, just run git diff --check before commit, and any extra spacing errors will be listed.
Commits should be small, complete changes to code
Two things to keep in mind is that a commit should always work by itself. If you have implemented a feature that took 20 commits, each of them must add (or remove) a part completely, and the program should remain fully functional. This does not mean that commits should be huge, containing hundreds of changed rows over days. Try to make small, incremental changes.
Message format 2
This is as essential a part as the others. A project that maintains the same messaging pattern is easier to understand and follow. It does not make much sense to be the only person on the project to work like this ... If you can get everyone to write messages in this format, things will be easier:
Instead of " I added tests to " or " Adding tests to ", use " Add tests to "
The example in the git documentation:
Breve (50 caracteres ou menos) resumo das mudanças
Texto explicativo mais detalhado, se necessário. Separe em linhas de
72 caracteres ou menos. Em alguns contextos a primeira linha é
tratada como assunto do e-mail e o resto como corpo. A linha em branco
separando o resumo do corpo é crítica (a não ser que o corpo não seja
incluído); ferramentas como rebase podem ficar confusas se você usar
os dois colados.
Parágrafos adicionais vem após linhas em branco.
- Tópicos também podem ser usados
- Tipicamente um hífen ou asterisco é utilizado para marcar tópicos,
precedidos de um espaço único, com linhas em branco entre eles, mas
convenções variam nesse item
The final hint is that if you register a default pro git editor with git config --global core.editor vim (for example), git is likely to start the editor with the formatting settings loaded, to warn you if you miss the format.
1. The documentation in git-scm.com is derived from a book which was not written by the git authors, but for all intents and purposes it is considered the official documentation. The Portuguese version is out of date, but that part has not changed much.
2. The list of formatting items is derived from How to Write a Git Commit Message (How to Write a Commit Message). I like the way the list is organized, so I used it. But it follows all the official documentation recommendations
05.05.2015 / 17:53