Let’s suppose you are contributing a feature to a project, tell me how can you evidently prove to the project maintainer that your code is working without actually running the code? Or how will you count the efficiency of a web application while developing it step by step? Let’s explore some useful development practices below.
Let’s say you are willing to start with one of your projects from scratch and you are already ready with a plan. With what approaches will you proceed and practice while developing it? Let’s have a look.
A must for any application is the “documentation”. You need to write proper docs of your project to make it more user-friendly and for other developers who are interested to contribute in your project. For example our Readme.md on GitHub represents the page where you write the documentation of your project. Let’s see what points your documentation may cover.
a) What the project is all about?
Here you may discuss your project objective and why was it needed and how it solves that problem. Many users just go through this part to see how much appealing idea your project is made up for. It can be as precise as one-liner at times
b) Fulfilling pre requisites and how to install the project?
Here you may discuss how to install your project and its dependencies (if any) on users/contributors machine, once s/he have downloaded the code.
Installation steps include how to build your code, and step-by-step commands need to be executed in order to develop a working code of your project.
c) How others can contribute to this project?
Different organizations and projects have different guidelines to follow while you are contributing to them. So, in this section you elaborate those guidelines, like how would you like your commit messages, what all things should be done before sending a pull requests to your repository, you need test cases, how to run existing test cases, how to report bugs in this project, what bug tracker you use, what code of conduct your organization follow, what are the pre requisites to contribute in this project, etc, etc.
d) Under what license your project is available?
Open source projects have a couple of licenses like MIT, GNU General Public License v3.0, etc. Which elaborates the permissions given to the one who takes this project in use.
If your project is big enough and you want to keep documentation like “developer’s guide” and “simple troubleshooting” apart from this Readme file, then you should give the links to all those docs here.
You may also add links to project website (if any), project blogs, contributors profiles, etc.
f) Description of folder structure
If you want to explicitly define your project directory structure and usage of different files available in it, then you may describe it here.
g) Documenting database models
Suppose you wanna develop a web app like with Django. And you must be knowing that creating the data models is one of the major and most important task. Because after creating the complete application it is difficult to alter them. Therefore, you may prepare documentation before implementing models in your app. The documentation should include what all models you are creating, what are their attributes and their datatypes and their description, etc.
This way if you are working in a team on GitHub and maintain DB model’s docs, then everyone can participate in the process of creating models by giving proposals of their own model design or improvement suggestions such as addition of more attributes, etc.
Once you are done with model documentation then any contributor can implement them. 🙂
Note: You may add more points and remove above points in your project documentation as per your need, like adding “solution of common problems faced in working of ‘X’ feature”, and removing “description of folder structure”, etc.
Documenting your code with proper comments is really important. Because even if you are the only contributor of your code, after months when you would go back to see what you were trying to do with “x” code block, that would seem confusing. Therefore, it is highly recommended that you should give proper comments to inform the objective of complex parts of codes that otherwise seems not clear.
In python we write function docstrings, there are not comments as we discussed above. But docstrings are special comments that self-document the purpose of a function. Suppose in python you wanna explore the usage of function “x”, what can we do is to go in its “help” documentation. That “help” documentation is nothing but that function’s docstring.
Giving proper names for keywords and functions such that they seem to be self-explanatory is vital to enhance the code readability.
d) Commit messages and description
If you are using a DVCS like git for your project, then giving proper commit messages and description is useful to describe the code you added/modified. Commit messages should be short, precise and upto the point only, such that it clearly shows what has changed with this code. And commit description is the place where you may describe in detail that
* Why was this change necessary?
* How does it address the problem?
* Are there any side effects?
This is yet another important part of documentation known as changelog. Changelog as the name suggest is a log of changes made in the project. Organizations maintain the changelog of new features added in successive versions of their product e.i see the Changelog of Oppia.
Or if you are making your personal project you may also maintain the daily changelog, where you describe what changes you are doing in your project daily.
Change log are not commit messages. Suppose you are adding a feature “x” in your project and did 10 commits to implement that feature. Now, your this “addition of feature” should be appended to your changelog not all the 10 commits. We can say that changelog keeps the log of all notable changes.
2. Test Cases
Whenever you add a feature to your project, there are possible ways that your feature could be used for. Here, for all those possibilities of use cases we write “test cases”. These tests checks the proper functioning of our code. For python beginners check out unit testing here.
Tests fulfil several purposes:
* They check the code we write is working how we expect (always a good thing to know)
* They provide examples for others about how to use our code.
* They quickly give us confidence that nothing is broken (running the test suite should take seconds)
* Most importantly, they allow us to make changes with confidence. If I update feature X, then run the test suite, I know I’ve not inadvertently broken anything else… 😉
It is always preferable to write test cases in a separate folder called “tests”
3. Continuous Integration
When you develop a project, you don’t write the complete code in one shot. Instead we develop it feature by feature. How can we make sure that adding one feature is not doing any harm for the existing code? Yes, test suit is the one way. But think about a repository where hundreds of contributors are contributing, they might have adding new features, or might be fixing some bugs, etc.
While they all can be sure using there individual test cases that locally there code is not harming the actual project, but how can a code maintainer make sure that after merging the feature of one contributor, will get sync with other contributors’ work without breaking the project?
Now comes what we call continuous integration. At a time one feature get merge with the code base and an automated tool will run test cases, not just test cases but also checks if the deployment of the project would be successful after merging this commit or not and take care of all the background work (as it is configured) like environment setup, operating systems, etc. One of the easiest tool for continuous integration I used on GitHub is Travis-CI. Learn to use TravisCI with this getting started guide.
Know more about continuous integration essentials.
4. Making a good Pull Request
There is reason why some pull request get merge sooner than others. Because there is way of making a good pull request.
First and most important make sure that you are following contribution guidelines of the organization to which you are contributing and sending your PR (pull request).
Your PR should include the following:
- Your Code patch (of cource, if it is not a pure documentation contribution)
- Documentation updates (if a new feature is added that needed to be documented in project’s docs, then please update the documentation)
- It also includes good commit messages, description, docstrings, commented code, changelog, etc.
- Test Cases (you must include test cases of whatever feature you are sending pull request to, which makes sure to the maintainer that your code is working)
- Update continuous integration file (i.e travis.yml if needed)
5. Get your Pull Request reviewed
Most important part of all. Once you make your PR make sure you get it reviewed by your mentor or any other developer.
At the time of review these experienced developers will let you know the wrong practices you are following while writing the code. And that’s how you’ll learn. They’ll also suggest you various ways and tools you may use to improve your code.
Doesn’t matter even if your complete code of a feature get in trash after the review, always take that code criticism positively, after all they criticize your code not you 🙂
Working on a project is pure fun for me! It brings you learning, make you comfortable with the technology you work on. You learn to get hands on the following practices that are being used in development of real software.
I’ll keep updating this post will more development practices I’ll get to know. If you know more good practices that we should follow while working on projects, then please feel free to write in the comments section below 🙂
Thanks for reading.