View source for Developer Area/How to Review Code

Here are the things to look for when reviewing code on the [https://reviews.mahara.org Mahara Gerrit]. These are not absolute rules, they are guidelines.

Also see our [[Developer_Area/Code_Review|commit / review policy]].

= Basic guidelines =

# If you're the first reviewer, you can +1 or +2 a commit.
# 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
* Version bumps on the stable branch '''should not use the current date''', they should just add 1 to the version number.

= Misc stuff =

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

* [[Developer_Area/Coding_guidelines|Coding guidelines]] should be followed unless there's a good reason not to.
* Curl: don't use directly, use <tt>htdocs/lib/web.php:mahara_http_request()</tt> instead
* No magic numbers: use constants instead of hard-coded numbers as much as possible
* No <tt>DIRECTORY_SEPARATOR</tt>: 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 assumes the presence of HTTP 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 [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html great git commit messages] is a good start. Other things to watch for:

* Unless the commit is trivial (e.g. typo fix, minor coding guideline cleanup), 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"
* If the bug is generic and relates to a blueprint, put in a tag to link it to that instead "Blueprint: blueprint-name"
* Click on the bug/blueprint number. Is it the right bug/blueprint?
* 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 <tt>|safe</tt> 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
* HTML comments should be avoided. Instead use a Dwoo comment like this: <tt>{* this is a comment that won't be in the final HTML output *}</tt>

= 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

= Javascript / CSS =

* Javascript and CSS is [https://developer.mozilla.org/Writing_Forward_Compatible_Websites forward-compatible]
* Javascript has semicolons at the end of each line (for maximum compatibility)

= 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)

= Useful links =
* [https://wiki.mahara.org/index.php/Developer_Area/Commit_Policy Commit and revision policy]
* [http://www.slideshare.net/rkabalin/how-mahara-code-revision-works How Mahara code revision works] - presentation on Mahara UK 11 technical workshop.