](https://image.slidesharecdn.com/bestpracticesinsoftwaredevelopment-200309132605/85/Best-Practices-in-Software-Development-13-320.jpg)
![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]](https://image.slidesharecdn.com/bestpracticesinsoftwaredevelopment-200309132605/85/Best-Practices-in-Software-Development-14-320.jpg)
Best Practices in Software Development
- 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