Most of my code related projects were done individually – as in , only by me. Mainly because the complexity of what I was doing wasn’t that high and the way I was doing it wasn’t the proper one. As I started bigger projects and as I began to have others collaborate with me on the same code, problems started appearing because there was no clear structure that allowed easy collaboration. To ease collaboration and make this go more smoothly we had to do some extra effort in regards to documenting what we were doing and the way we coded.
Documentation
Normally, most people omit documenting all the details in their work based on the fact that they “know it already”. This becomes a problem for that individual when he has a look on the code after a while or when others are getting in. The README file in the project should give anybody a good idea (at first sight) on what the project is about and how it is structured.
- diagrams – flow charts, activity, use case – a visual overview of what the project is to be used like and how to code should operate, followed by a description can make people understand much faster than by explaining what is it about.
- directory and file structure – due to organization and security, you can end up with files in different places that are linked in different ways. You can easily lose track, without a general overview
The way I do it is by getting a tree structure by running the tree /path/to/dir
projectfolder ├── files │ ├── file1 │ └── file2 ├── includes │ └── dbfile.db ├── public_html │ ├── login │ │ ├── index.php │ │ ├── loginbox.php │ ├── media │ │ └── web-final-logo.png │ ├── src │ │ ├── auth.php │ │ ├── main.php │ │── index.php
And by having diagram like below:
- in-code comments
- including other projects / files – when the code is to be tested in a different location, you should be able to do it in a fast and efficient way (e.g. simply by cloning the project or by downloading it). When other projects are included (e.g. other projects hosted on github), the user should be able to read from the documentation and copy-paste the commands needed to get the project. I used the example below with FlatUI for one of my projects, that can be linked with the diagrams above :
cd aboxwebui/public_htmlgit clone https://github.com/designmodo/Flat-UI.gitmv Flat-UI flatui
Code development
For a better experience it should be expected that participants are to use version/revision control software such as Git.
Description
- the names in the diagram are branch names
- “Release” is the stable and ready for usage branch, that should not be worked with directly, but it should get merged with the “Development” branch
- “feat_A” and “feat_B” are branches created by separate collaborateurs when they want to add a new feature in the code. It is not to be added directly in the “Development” branch, but it is be tested beforehand if it does not brake anything.
- the way the new branches are created is by creating them from the branch onto which we want to add .
In other words, when we want to implement a new feature in our code we would follow the next steps in Git. My example is based on Eclipse, but there are command-line equivalents too.
1. Getting the latest code from the repository
Right-click on project -> Team -> Fetch from upstream
2. Switch to the branch that you want to update
Right-click on project -> Team -> Switch To -> select your branch from list or click “Other” to select from remote lists
Team -> pull changes
3. If there are any modifications from last time you switched to branch, pull the modifications.
Right-click on project -> Team -> Pull
4. Merge with the branch that you have been modifying. The screenshot below illustrates how I am merging the “Development” branch with the “intg_api” branch.
Right-click on project -> Team -> Merge
5. Push modifications to repository
Right-click on project -> Team -> Push branch
6. Switch back to your branch and continue development
Right-click on project -> Team -> Switch to -> branch_name
All of the above was the raw and minimal setup that I had in place to ensure a proper workflow and to allow others to easily join in on my code. Things can, of course, be done much better and professionally, but I think that if you can properly document your work and stick to some minimal best practices it is good enough. Speaking of best practices, one might be interested in more details, which can be found here or here.