Clean code, clean commits and clean PR
If you are a software developer, you write code, commit changes, and open pull requests. Do you have good practice for them? Here I will note my tips. They’re quite simple but really important.
1. Write clean code with a clean design
Of course, this is the most important thing for sake of readability, maintainability and scalability. But do you know what is clean code and what is clean design? Maybe it depends on your preferences but these are books and posts which I was impressed with.
- The Art of Readable Code
- Practical Object-Oriented Design in Ruby
- Android — Clean Architecture — Kotlin
2. Describe specs and proof their behaviors
For me, testing is important as well as main code because they show how our classes/modules work. My first testing framework was RSpec. When I was wondering how to write good Rspec, I found Better Specs. It helps me a lot to figure out what is the best practices for tests. It’s talk about RSpec but I believe we can follow it with Jest or whatever testing framework.
If you want to know how you should describe behaviors themselves, fortunately, we have a nice article on Wikipedia - Behavioral specifications.
3. Leave semantic commit messages
Have you ever seen commits like these?
Well, they’re pointless. We don’t know which kind of changes were made and how important each commit is. One thing I highly recommend is following Conventional Commits which makes commit history explicitly. If you want to make it a rule, you can use commitlint. If you get familiarised yourself with conventional commits, you realize that your commits are easy to be modified (re-order, drop, etc..) because a semantic message means the commit has a semantic chunk.
Also maybe you want to clean up commit history before you open a PR. That’s the time you use $ git rebase [-i | — interactive].
If you want to know a more general idea of how you build clean commit history, this is where you go next.
4. Open easy-to-review pull requests
Once you write clean code and push clean commits, finally you open a PR. I agree with the One Pull Request - One Concern rule. If you mix up more than one thing in a PR, it’s quite hard to review. Also if we found something wrong with it after the merge, it’s tough to revert because we have to extract the problem part. It’s like surgery. Great pull requests lead to great code reviews. These are posts you should check out.
When you like how descriptive your pull requests are, probably you’re annoyed to write down the same headers or whatever in your every pull request. Then you can add your template to your project. There is no standard format for pull requests but as far as looking around, this post shows a simple and good example. Let’s start with a simple one :D
Once you follow all of them, your code and pull requests will get love from your folks.
Happy coding!