Die Sache mit den Versionskontrollsystemen (CVS, SVN, Git, etc) wurde mal eingeführt um einem Team von Entwicklern eine gemeinsame Codebasis zu ermöglichen. Wenn der Entwickler den Code ändert, wird er bei einchecken auch immer zu einem Kommentar der Änderung aufgefordert. Darüber kann er dem Team Infos über die Änderungen mitteilen. Nach meinen Erfahrungen wird diese Funktion leider nur selten dazu benutzt, sinnvolle Informationen mitzuteilen. Beispielsweise sagen Einzeiler wie “Updated acctList” oder “Added working folderAddMember” nichts über die Änderungen aus. Auf progit.org findet sich eine gute Beschreibung für Commit-Messages:
Getting in the habit of creating quality commit messages makes using and collaborating with Git a lot easier. As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, followed by a blank line, followed by a more detailed explanation. The Git project requires that the more detailed explanation include your motivation for the change and contrast its implementation with previous behavior — this is a good guideline to follow. It’s also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of “I added tests for” or “Adding tests for,” use “Add tests for.” Here is a template originally written by Tim Pope at tpope.net:
Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Further paragraphs come after blank lines.
– Bullet points are okay, too
– Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
If all your commit messages look like this, things will be a lot easier for you and the developers you work with. The Git project has well-formatted commit messages — I encourage you to run git log –no-merges there to see what a nicely formatted project-commit history looks like.
In einer Zeit von häufigen Commits (Continuous Integration) ist es verständlicher weise aufwändig jede kleine Änderung (Typos, UI alignements, Code Formatierungen, etc) zu kommentieren. Meine Empfehlung wann ein Entwickler eine ausführliche Message schreiben sollte:
- Wenn sich ein Klassenname ändert oder eine Klasse verschoben wird
- Wenn sich die Signatur einer Methode ändert
- Wenn neue Bibliotheken verwendet werden
Diese Liste könnte sicherlich noch um einige Punkte ergänzt werden, aber prinzipiell geht es um Änderungen, die die Struktur des Codes oder des Projekts verändern, quasi Refactorings.