aliases: clc-wiki:Procedures:Code reviews [primary] | Clc:Code Reviews (for this wiki) | Clc:Code Reviews
From clc-wiki
Review components
A reviewer of code on the wiki may perform any of the following tasks:
- syntax inspection: visually check that the code contains no invalid syntax
- style inspection: visually check the code for consistent style conforming to this wiki's style guidelines
- portability inspection: visually check the code for undefined, unspecified and implementation defined behaviour; verify that the result of your inspection matches the "portability" parameter of the code's summary line
- compilation: attempt to compile the code with one or more C compilers in Standard mode
- casual testing: perform tests on the compiled program by submitting it to adhoc or random input, without attempting to be rigorous
- structured testing: as above but with a rigorous approach wherein the test inputs have good justification and can reasonably be said to be an attempt at completeness; likely this will involve a test harness
- behaviour inspection: visually confirm that the code matches its advertised behaviour (an alternative to failing the code on this basis is to edit the wording of the "advertising")
- desk-check: step through the code's algorithm on paper to confirm that it functions as advertised
- formal validation: perform some formal validation of part of the algorithm as appropriate, such as mathematically deriving/proving any formula used.
Review types
As listed in the summary line following each code block, the types of review are:
- cursory: the review did not go beyond inspection
- partial: at least one type of inspection review as well as at least a compilation test was performed (for complete snippets a compilation test must obviously be performed by incorporating the code into an appropriate container)
- complete: all types of review possible were carried out. Some types of review are not possible for certain code blocks - e.g. for a simple snippet or function there may not be anything of sufficient complexity to warrant a formal validation. A complete review should always include structured testing where the code contains one or more functions with inputs and outputs.
Post-review editing
After reviewing the code, add your findings to the summary line - if a summary line does not yet exist then first add one.
Add any more specific details that you wish to be made known either in the article below the code, or to the article's talk page as appropriate (with the aim of minimising clutter in the article). The talk page entry should include a "signature" - i.e --~~~~
, which expands to your username and a timestamp, available as a shortcut in the graphical editing toolbar.
Details you could (in the case of a review that fails code, should) include are:
- the specific set of review components that you performed
- if the code failed your review, the specific reason(s) for that failure
- test harness code, data and rationale
- compiler warning messages
- formal validations, proofs or equations.