In FTBpro.com, we have a nice procedure of merging new code to our master branch. We use GitHub’s neat Pull Request (PR) feature to gain two big advantages:
1. It is easy to see the commits and the files changed in the branch compared to master. It is a very good tool for code reviewing.
2. Our Jenkins CI server automatically makes a build of the merged branch to verify all the specs run, and marks the PR with success/failure accordingly.
I want to extend the first point a little bit more. Going through code review is not always an easy experience: It may have taken the programmer days or weeks to produce this pull request. A lot of effort was made to meet a deadline or even free hours spent on finishing the job, and now his/hers PR is not approved due to lacking code quality.
So what a developer should do before submitting a PR to be reviewed by his peers?
Look at the the diff and ask himself one, very simple but yet powerful, question: Am I proud of the code I delivered? If I were looking at this diff, would I think it is an excellent code?
Once this question is positively answered you know you made your best to submit high quality code. It may still get some rejects or corrections from peers, but that’s only natural – the more eyes, the better your code gets.
Of course being proud of your code is very subjective and changes from person to person. How can you really know that the code you’re proud of, will be appreciated the same by someone else’s point of view? You can’t, but you should endorse yourself a set of rules which makes you feel good about the code you write, and try to apply them every time you submit new code.
I’m going to present you with my set of rules. Some of them may fit you, others may not, with some you may agree and with some you may disagree. This is what makes me feel good about the code I write.
Working Code Is Nothing To Be Proud Of
I think that the strongest thought that sits in the back of my mind while writing code is this one. Once you change your state of mind from writing code that works, to writing an excellent code that works, you can never go back. You always seek where you can improve it so that it stands out as an excellent piece of code. Think about it this way: Every 15 years old boy can probably submit a code that does exactly what you are trying to do. So what makes you, a mature and experienced developer, better? What knowledge do you have that this boy does not, and how is it applied in your code? What makes your code above average?
Be honest with yourself answering these hard questions and make sure you have an answer to at least one of them when submitting the code.
Become A Writer
Grady Booch, author of Object-Oriented Analysis once said something very powerful: “Clean code reads like well-written prose”.
All modern, high-level programming languages strive to allow the developer write code that reads like well-written prose. From all the languages I’m familiar with, Ruby wins the prize in this category. You should always strive to write code that reads like plain English. Hide the implementation details as far as you can. Use meaningful yet simple names for you classes, functions and variables.
Before submitting a PR go over the code you’ve written and make sure it reads like well-written prose. Believe me, when you go over your own code and it looks like plain English, the satisfaction will keep you going this way forever on.
Test Your Code
Tested code has its obvious advantages.
Once the test suite is done, refactoring is a piece of cake. Extending the module or class is easier since the developer can be sure nothing old is broken. It is even a good documentation tool since reading the test suite must convey the purpose of each public/interface method you present.
Apart from these obvious advantages there’s another one which lays underneath the surface: Writing tests is a process in which you, the one which creates the system, takes the role of the client which uses it. Seeing your code from the client’s perspective is a whole different matter. You get insights that you couldn’t get in any other manner. Suddenly, instead of thinking “what would be the easiest way to implement this feature” you start thinking “what would be the easiest way for the client to use this system” and that makes your improve your interface, method naming and code modularity.
Refactor When Possible
Often we alter or extend a module that was not written by us. Most of the time we’re thinking to ourselves: “If only I were the one writing this code, it would be 10 times better” but the timetable and deadlines make us give up on refactoring it.
I know that a total refactoring process can take days or even weeks for large modules, and there isn’t always time to perform them. But even in large modules like these, small, precise refactorings can make a difference: You can change a method or a variable name to a more meaningful one, eliminate small code duplications, extract a few code of lines to a well named method or even put one break statement that will save us going over a whole collection when the object we wanted was already found. All of these does not require much time, and affect only small portions of the code.
Always leave a cleaner code behind you.
These are the things that makes me proud of my commits. When I apply them I feel like I contributed to a better, more maintainable code base. The feeling of being proud of your commits is an addictive one and that’s a great thing: Once you’re there, you can never go back.
Now go, make yourself proud 🙂