kychua
commented
7 years ago -
Audience: CS3281/2 students
-
Objective: Encourage better commit messages
-
Topic: How to write better commits
-
PUNCH: example of when a commit message is useful
-
WIIFY: Learn to become a better developer & team member
-
Promise: How to use commits as a form of documentation
-
Content
-
Commits are a useful form of documentation
- Different forms of docs: UG, DG, README, comments, tests
- Something they don't cover: context
- Also might become outdated
- But commit messages are always there
- Always updated
- No length constraints
- Go beyond comments
- Sticky-> near code
- Searchable == Good commits save a lot of time and frustration when trying to understand old code or code written by other people
-
How to write good commits
- structure: formatting, 50/72 rule
- content: don't break build, atomic == good commits facilitate debugging
- good commit messages
- Why is the change needed?: fix bug, improve performance, feature
- How does the commit solve the issue?
- Why did you choose this approach?: tradeoffs, other alternatives? difficulties?
- What are the side effects?: impact on performance, other code, break build? user needs to take action?
- What are the limitations?: known limitations, future scope for improvement
- Useful references: useful resources, past commits, bug tracker
- Giving credit/acknowledgements == writing good commit messages forces you to think about your code
- readable history == good commit messages make it easy to see what has changed in the code base
Key points: Good commits & commit messages
- make it easier to stay updated on changes in the project
- makes debugging easier by documenting the context of code changes
- improves quality of your code by forcing you to think through your decisions
Call to action: Let's start writing better commits today!
Do: write better commits Believe: it is worth their time Know: how to write good commits, why it's important to do so
Synopsis
Slides are here