-
Notifications
You must be signed in to change notification settings - Fork 1
Development Guidelines
This page contains guidelines that all project members should follow when producing new source code for the UnBall Robot Soccer Team. These rules aims to produce consistent code, which can be easily understood and maintained.
The most important coding style is: be consistent. Writing code in a consistent style makes it easier to read, hence, it is strongly recommended to follow the coding style suggestions below.
- Identation: Indent 4 spaces at a time and use spaces only.
- Line Length: Each line should be 120 characters long.
It is not easy to develop software with many people in a team: everyone needs to be working (preferably) on the same version, and, sometimes, changes across files may conflict. Also, it may be necessary to consult a previous version of a file in order to undo some changes. Therefore, it is a standard approach to use a Version Control System (VCS).
A VCS allows you to: revert files back to a previous state, revert the entire project back to a previous state, review changes made over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more. Using a VCS also means that if you screw things up or lose files, you can generally recover easily. In addition, you get all this for very little overhead.
Git is the version control software used by the UnBall Robot Soccer Team.
A project is usually hosted on a Git server, which may be on GitHub, Google Code or even your own computer. Cloning is the act of getting a project from the server and place it in a directory. This is achieved by the command git clone <url>, which need to be executed only once.
Example:
git clone https://github.com/unball/ieee-very-small.git places the project on the "ieee-very-small" directory.
If you already have a cloned repository, it is important to synchronize it to the latest version whenever you start to work. This will avoid merge conflicts due to different versions of the project. The command to get the latest changes is git pull.
Differently from a Dropbox folder, placing a new file in your project directory is not enough to add it to the project. This is a useful feature since there are lots of files which we should avoid to insert to the project, for instance, executables or object files (only important during compilation). To insert a new file or directory, use the command git add <file or dir>. Note that adding a directory is recursive, which means that all files inside it will be added.
Example:
git add hello_word.cpp adds the recently created file "hello_word.cpp" to the repository.
After working on the project, you should tell the other developers what you changed what the reasoning behind it. In order to do it, you should commit using the command git commit. You may commit file by file or all changes using the flag -a.
A text editor will appear for you to write a log, a small message that describes the modifications. It is really important to write clear and direct log messages, so the others may quickly understand what was modified, and also to show what this commit is about in the project history. The log message may also be written in the command line by using the flag -m.
Example:
git commit -a -m "Created a new class in the simulator for the ball. All tests passed.".
After committing, there is one last step necessary to upload your modifications to the Git server: the push. Git allows programmers to work offline, which means that all your commits will stay in your computer until they are pushed to the server. This is done by the command git push. Usually, it will require your username and password for the GitHub server (where the UnBall Robot Soccer Team is hosted).
- Commits: Should be small and change only one thing in the project. It is better to have hundreds of small commits, that are easily reverted if anything goes wrong, than few colossal commits that changes several files at the same time.
- Log messages: Make the log messages clear and instructive. Any developer should be able to understand what was changed and why by only reading the log.
- Never commit broken code: Your code must have passed all tests and yield zero warnings before it can be committed to the project.
- Always pull the latest changes before start working on the project: This will avoid merge conflicts.
- Do not add object or executable files to the project: They are changed each time the project is compiled and will keep appearing on the commit logs.