Developer Area/How to Review Code

Here are the things to look for when reviewing code on the Mahara Gerrit. These are not absolute rules, they are guidelines.

Also see our commit / review policy.

Basic guidelines

1. If you're the first reviewer, you can +1 or +2 a commit.
2. If you're reviewing something that's already +1, you cannot just give it another +1. You must take the other review into consideration and give it a +2 or you directly invite another person to review and give a +1.

Verification

The rest of the guidelines apply to the "code review" part of Gerrit. These ones are for the testing or "Verified" part:

• If you submit a change, you can mark it as verified unless you specifically want others to test it.
• Only mark as verified a change that you have tested yourself by checking out the right review branch (use the command line given by Gerrit).
• When appropriate, briefly describe what tests you did in your review. For example "tested fresh install on Postgres and MySQL, works fine"

Database

• Make sure there are no unnecessary DB queries being added
• Watch out for queries inside loops (do it outside the loop all at once in a si query)
• Table names in queries should be surrounded by {braces} so that prefixes will be applied if needed.
• SQL injections
  • use placeholders in queries, no exceptions
  • ideally, do the validation of the parameters close to where they're used so that it's obvious that it's validated
• When the database schema is changed, the same changes should be made in the install.xml and in the upgrade.php

Misc stuff

A few things which don't fit in the other categories but are important to keep in mind:

• Coding guidelines should be followed unless there's a good reason not to.
• Curl: don't use directly, use htdocs/lib/web.php:mahara_http_request() instead
• No magic numbers: use constants instead of hard-coded numbers as much as possible
• No DIRECTORY_SEPARATOR: always use the UNIX path separator when opening files (it works on Windows NT too)
• Too much inline HTML? Please move it to a Dwoo template.
• JSON: new code should always use json_reply() rather than json_headers(), etc.
• HTTP headers: when writing code that deals with headers, think about cron running in CLI mode
• Slow operations should ideally be done in cron

Commit message

The commit message is part of what we review. This article about great git commit messages is a good start. Other things to watch for:

• If the commit fixes a user-visible bug, it should have a bug on the tracker and the bug number should be included somewhere (doesn't have to be the summary line) in the commit message like this: "bug #123456" or "Bug #123456"
• Think of the reviewer: your "commit message + the diff" needs to tell a story: why you changed the code in that way. The reviewer may need to go back to the bug on the tracker to see how to reproduce exactly the original problem, but your solution should be clearly explained in the commit message if it's not obvious from the code.
• When you fix a bug something introduced in a previous (recent-ish) commit, mention the commit hash in your commit message.
• If adding a new feature, briefly describe the feature, don't assume the reviewer will know all about the fancy Web 2.0 service you're adding a plugin for (at the very least in this case, you should include the URL of the service).

Langstrings / help files

• Apart from messages to the logs, everything should be translatable
• Check for grammar / typos

Templates

• Style attributes in the templates are discouraged because it makes it impossible to theme these elements. Move this css stuff to the raw stylesheet instead.
• Check for cross-site scripting problems:
  • watch out for |safe in templates, it should only be there when the HTML is outputs is not coming from the user (or has been cleaned through Purifier)
  • templates should be escaped by default

Forms

• Check for cross-site request forgeries
  • forms should ideally use pieforms which has a built-in session key check
  • non-pieforms forms should include the sesskey and check it on submission
  • other operations that change the state of the application need to check the session key before doing anything

New upstream components

• our patches are maintained but not mixed in with upstream code
• upstream doesn't add new dependencies
• check if there are new copyright statements (which could lead to GPL-incompatible code being added to our codebase)
• make sure a README.Mahara exists for that external component. look at htdocs/lib/htmlpurifier/README.Mahara for a sample one
• do not change upstream code at all when adding it to Mahara. if you need to patch it to fix a bug, do that in a separate commit and make a note in its README.Mahara
• we shouldn't fix coding-guidelines related problems in external code. Delete the Jenkins review and link to the relevant console output in your review (e.g. https://jenkins.mahara.org/job/mahara/414/console)