BBS Ordering Principles
In my research on ordering code changes for review (together with Alberto Bacchelli and Kurt Schneider), I developed the following set of principles how to order a set of interrelated code changes to ease understanding:
- Group related change parts as closely as possible.
- Provide information before it is needed.
- In case of conflicts between Principles 1 and 2, prefer Principle 1 (grouping).
- Closely related change parts form chunks treated as elementary for further grouping and ordering.
- The closest distance between two change parts is "visible on the screen at the same time."
- To satisfy the other principles, use rules that the reviewer can understand. Support this by making the grouping explicit to the reviewer.
By replacing "change part" with "section/item/stuff" and "reviewer" with "reader", the principles are probably applicable to many other areas beyond change-based code review.
For more details, read the full paper.