The 3 common ways for developers to document information about their work is:
- Comments
- When is this written: When the developer wants something to be clearly and immediately visible to all other developers
- When is this found: As soon as other developers are reading code, they will find these comments
- Commit messages
- When is this written: When the developer wants to explain the work involved in them making a change. Why a change was made, explanation of the
- When is this found: When other developers dig a big deeper on why or when a change was made - they will find these commit messages
- Tech Documentation
- When is this written: When the developer wants to explain a complex piece of work or an architectural understanding, they use other documentation tools like confluence etc to explain them
- When is this found: When a developer is explicitly looking for some information, they may find this information. Because this is separate from the standard tools developers use, it is not as easy to find - in many cases teams use markdown files in the git repo to avoid using a completely separate tool.
Hence, having good commit messages is a very important thing. And adding consistent commit messages (similar to consistent code styles) can be very helpful. There are multiple guides on how to write good commit messages:
- https://cbea.ms/git-commit/
- https://dev.to/wordssaysalot/art-of-writing-a-good-commit-message-56o7
- https://dev.to/wordssaysalot/art-of-writing-a-good-commit-message-56o7
But every developer still writes it in a fairly different way, which is why some standard formats have also been created. Like:
Along with these, there are also tools to help beginners to write the commit messages in this standard format. Mainly:
- Tools that help in preparing the commit message
- Tools that help validating commit messages (linters)