Code review (Wikipedia) is an essential tool when developing quality software. We welcome interested persons and provide some general information about it here.
How to start¶
The code is available at GitHub and you'll find links to demo versions and manual, used technologies and much more on the OpenAtlas website.
Information about development is available in the Redmine Wiki which you may already know since you are here.
We recommend using your favorite editor to analyze the code and install OpenAtlas locally to e.g. run tests or check changes on the fly.
Etiquette¶Giving and receiving critique can be hard, we are humans after all, but here are some tips to make it easier and friendlier for both parties involved:
- Be polite and respectful, e.g. thank for comments and suggestions. Even if you don't agree, someone made an effort to communicate something.
- Be factual instead personal e.g. use "this function" or "that suggestion" is faulty instead of "you are"
- Try to make suggestions or give examples how to improve something instead of just criticizing an existing solution
- Don't repeat yourself, e.g. if you find a misspelled variable name (grammar), note it once and not everywhere it was used
A good read about working on code together is The Ten Commandments of Egoless Programming, as originally established in Jerry Weinberg's book.
What to look for¶
- Security issues
- Code readability
- Unhappy paths (Wikipedia)
- Architecture (e.g. use of frameworks or their lack of)
- Documentation (code comments, manual, installation notes, ...)
- Tests and coverage
How to participate¶When you find issues we like to hear about it and there are some ways to tell us:
- Giving feedback in a meeting with the developers
- Creating Redmine issues (registration required)
- Using Git, e.g. making pull requests or even do work in a separate branch. It's recommended to make (at least) one commit or pull request per issue.
- Write an email to firstname.lastname@example.org
Things for us to do¶
- Expand this article
- Think about using more automatic checker for e.g. formatting and security to not bother our reviewers with easy to avoid issues.