This presentation has some tips about how to write better commit messages, review and write pull requests.

1. Best Practices in Software
Development
André Luís Pitombeira

2. Agenda
● Software Maintenance
● Code Review
● Using Version Control
● Commit Messages
● Pull Requests

3. Software
Maintenance
Reports suggest that the cost of
maintenance is high. A study on
estimating software maintenance
found that the cost of maintenance is
as high as 67% of the cost of entire
software process cycle.

4. Code Review
Peer review – an activity in which people other than the author of a software
deliverable examine it for defects and improvement opportunities – is one of
the most powerful software quality tools available.
… software testing alone has limited effectiveness – the average defect
detection rate is only 25 percent for unit testing, 35 percent for function
testing, and 45 percent for integration testing. In contrast, the average
effectiveness of design and code inspections are 55 and 60 percent.

5. Code Review
● Developers tend to think of productivity in terms of “how fast can I write the code for
this new feature”.
● We also tend to say “I write code” when describing our jobs
● Professional software development is a matter of understanding the code that is
already there: we simply spend much more time reading than writing
● Productivity thus depends more on the overall code’s quality and maintainability,
rather than the skills of individual contributors making changes.

6. It’s harder to read code than to
write it.

7. Using Version Control
● What constitutes a particular version of your software?
● What was done when, by whom, and for what reason?

8. Commit Messages
● Every version control system has the facility to add a description to your
commit
● Many people get into the bad habit of omit the description
● The most important reason to write a descriptive commit message is so
that, when the build breaks, you know who broke the build and why

9. Commit Messages
1. You find a bug that is down to a rather obscure line of code
2. You use your versions control system to find out who put in that line of
code and when
3. That person is off on holiday or has gone home for the night, and left a
commit message that said “fixed obscure bug”
4. You change the obscure line of code to fix the bug
5. Something else breaks
6. You spend hours trying to get the application working again

10. Commit Messages
● A commit message explaining what a person was doing when they
commited that change can save you hours of debugging
● There is not prize for shortests commit messages
● A couple of medium-to-long sentences with an overview of what you were
doing will often save you many times the effort later on

11. Commit Messages
● Write a multiparagraph commit message
● The first paragraph is a summary
○ This is what gets shown on line-per-commit displays
○ This is like a newspaper headline
● The following paragraphs add more details
● Add a link to the identifier in your project management tool for the feature
or bug you are working on

12. Commit Messages
Bad commit message:
add cli new
fixes
fix code review comments
wip

13. Commit Messages
Good commit message:
Make Source.indexOf(ByteString) significantly faster
Previously the algorithm that did this was extremely inefficient, and had worst case runtime of O(N * S * S) for N is size of the
bytestring and S is the number of segments.
The new code runs in O(N * S). It accomplishes this by not starting each search at the first segment, which could occur many
times when called by RealBufferedSource.
---
Issue: [#365](https://link/to/issue/365)

14. Commit Messages
Good commit message:
Add updated credit card icon for sbs reservations
At first we wanted to use the same icon as on the new TM but since in
the list it is a background image, the only way to apply a correct color
to it would be using mask-image css property which is not supported in
IE11. That’s why we duplicated the icons for now until the list will be
moved to Angular and both will be able to make use of the inline SVGs
[BC-3985]

15. Pull Request
● Reviewing pull request is hard
● Make smaller pull requests
● Write useful descriptions and titles
● Have on-point commit messages
● Add comments on your pull request to help guide the reviewer
● Make it visual

16. Pull Request
Approach to writing a Pull Request
● Include the purpose
● Consider provide an overview of why the work is taking place
● Be explicit about the feedback you want
● Be explicit about when you want a feedback
● Mention individual you specifically want to involve in the discussion
● Mention teams you want to involve in the discussion

17. Pull Request
Offering feedback
● Familiarize yourself with the context
● If you disagree strongly, consider giving a few minutes before responding
● Ask, don’t tell (“What do you think about trying?” Instead of “Don’t do!”)
● Explain your reason why the code should be changed
● Offer ways to simplify or improve the code
● Avoid using derogatory terms like “stupid”
● Be humble (“I’m not sure. Let’s try...”)
● Avoid hyperbole (“Never do...”)
● Be aware of negative bias with online communication. Can you use positive language instead of neutral?
● Use emoji to clarify tone

18. Pull Request
Responding to feedback
● Consider leading with an expression of appreciation, especially when feedback has
been mixed
● Ask for clarification. (“I don’t understand, can you clarify?”)
● Offer clarification, explain the decisions you made to reach a solution in question
● Try to respond to every comment
● Link to any follow up commits or Pull Requests
● If there is growing confusion or debate, ask yourself if the written word is still the
best form of communication

19. Pull Request
How can we get started?
1. Code reviews guideline
2. A pull request template
3. Useful resources about how to do this well

20. Questions?

21. References
● What makes a good commit message
● The (written) unwritten guide to pull requests
● How to write the perfect pull request
● Code Reviews: Just Do It
● Code reviews: getting started
● Continuous Delivery
● Software Maintenance Overview

22. Thank you