Building a Magik Review Checklist Inside Emacs

When a Smallworld code base grows past a few thousand lines of Magik, peer review stops being optional. Anything beyond a quick glance at a pull request needs to be tracked, ticked off, and ideally reproduced by the original author without scrolling through chat logs. A lightweight checklist living inside the editor turns each reviewer session into a measurable artefact, especially in Australian utilities where field offices in Brisbane, Perth, or Adelaide often push changes to the same central repository across several time zones.

The Emacs environment already speaks Magik fluently through the extensions maintained by HydePark Consulting. By combining those tools with a small handful of built-in features — outlines, dedicated buffers, and a touch of Elisp — a reviewer can spin up a private to-do list for every change, capture observations at the exact source location, and keep the conversation anchored to the code rather than to email threads that drift off topic.

Why a reviewer checklist matters in a Smallworld shop

Smallworld projects tend to spread across long-lived modules: network modelling, collection navigation, dynamic object inspection, and reporting pipelines. A single commit might touch several of these concerns at once, and reviewers working across different regions — say a GIS analyst in Melbourne and a back-office engineer in Parramatta — need a shared rhythm to avoid subtle regressions slipping through unnoticed.

A checklist makes that rhythm explicit. Instead of relying on memory or hurried chat windows, the reviewer enumerates each concern in advance: dynamic method dispatch, inheritance chains, database transactions, exception paths, session resource cleanup. The list becomes a contract that both author and reviewer can refer back to. It also doubles as evidence during an audit, which matters for organisations covered by Australian regulations on critical infrastructure, where code changes affecting outage modelling or pressure calculations must be traced back to a reviewer’s sign-off.

Practically, the checklist keeps the review focused. Australian engineers used to juggling multiple projects appreciate a structure that prevents a long review from drifting into a re-design discussion. Each item is finite: either the line is acceptable, or it needs a follow-up commit. The discipline of crossing items off also produces cleaner review notes for stakeholders who only want a short summary — a one-page executive report can be assembled from the same buffer in minutes, which is a useful habit for teams supporting boards that meet quarterly to review pipeline investments.

Setting up a dedicated buffer with Magik mode

The first step is reserving a buffer for the review. Many practitioners create a file named after the change request, such as review-CR-4521.org, in a folder shared across the team through NFS or a Git LFS-backed store. Because Magik files and Emacs buffers share the same encoding conventions, no conversion glue is required and the document opens instantly on any workstation.

Switching the buffer into a Magik-aware major mode gives immediate benefits. Syntax highlighting applies to any code snippets pasted into comments, and indentation rules stay consistent whether the reviewer is summarising a method definition or quoting a snippet of session output. For teams that prefer Org mode for collapsible sections, simply enabling org-mode with magik-syntax as a local variable keeps the document both readable and structured, and the familiar TAB cycling behaviour makes the checklist feel familiar from day one.

Australian teams often work hybrid, and the buffer travels with the reviewer from the office to the home setup. Saving the file to a synced directory — many consultancies in Sydney rely on Dropbox or OneDrive, while larger utilities lean on internal SharePoint or Git servers hosted in Australian data centres — ensures that progress made during a late-arvo review is still visible the next morning on the office network. A short header comment noting the reviewer’s name, the change number, and the relevant module helps everyone identify ownership at a glance, particularly when multiple reviewers in different states collaborate on the same change.

Capturing TODO items straight from the source buffer

The real power of the approach comes from capturing observations without leaving the code. With a keybinding that copies the current line number and method context into the review buffer, the reviewer stays in flow. A typical capture, configured through a small Elisp function, produces a bullet that reads:

TODO [src/collections/network_model.magik:482] _add_junction
  - confirm NPE guard for nil geometry
  - verify transaction scope is restored on rollback

The function itself is short: it reads the line number, the enclosing define_method or _method declaration, and the buffer file path, then inserts a Magik-flavoured comment into the review file. Because the comment uses familiar Magik syntax, highlighting inside the review buffer stays accurate even when the reviewer pastes a multi-line snippet. A reviewer in Perth who opens the same file the next morning sees the line numbers, the function names, and any inline code block rendered exactly as the author would — including syntax colour highlighting that survives the journey between machines.

This pattern also helps with method navigation. Emacs extensions for Magik can jump straight to a captured line using magik-edit-method or equivalent, so each bullet is directly actionable. When the author returns to address each point, a simple click or keypress places the cursor on the offending line, ready for the fix. Reviewers in regional offices — say Cairns or Bendigo — appreciate this because connectivity overhead is lower and the workflow is optimised for a connection that drops in and out.

Linking review notes to buffers and change requests

A review checklist is only useful if it connects back to the change under review. Adding a few lines of metadata at the top of the buffer turns the document into a lightweight hub. Fields such as the change request identifier, the branch name, the build pipeline run, and the reviewer’s handle can be set with org-set-property or simple Emacs text-properties. Auto-deploy jobs from Australian platforms such as Octopus or internal Bitbucket runners can be referenced by run number, which makes it easy to trace a regression comment back to a specific artefact without leaving the editor.

For larger teams, a small snippet that links each TODO bullet to the matching source line through an org-link style file:line:column path is invaluable. The link keeps the structure portable: clicking through from the review document opens the precise line in the source buffer, even when the reviewer is in a different state or on a different network. It also supports offline work — a real benefit for engineers travelling to remote sites in regional Queensland or Western Australia where connectivity drops in and out and VPN tunnels can be unreliable.

When comments need to be aggregated for a stakeholder update, exporting the buffer as plain text or Markdown produces a tidy summary. An entry like [network_model.magik:482] NPE guard reads well both inside Org mode and in an email footer, and it keeps the conversation narrow without losing technical precision. A simple C-c C-e export, configured in init.el, reduces the chore to a single keystroke before the morning stand-up — which keeps the workflow efficient through the busier weeks leading up to the end of financial year.

Sharing the checklist without losing local context

Australian teams often span multiple offices, and not every reviewer can sit beside the author. Sharing the review buffer through Git — committing it into a dedicated reviews/ directory at the root of the repository — preserves history, supports blame, and lets multiple reviewers append items without overwriting each other’s notes. Before pushing the change back, the original author merges the review file with their own progress, leaving resolved items prefixed with DONE and unresolved ones still flagged.

A short policy helps adoption. Reviewers are encouraged to write bullets in the imperative mood, mirroring Australian engineering culture where direct, plain-language feedback is preferred over softening hedges. Phrases such as “wrap in try” or “extract helper” read cleanly, and they line up with the way Magik keywords themselves are written — terse, descriptive, no fluff. Local touches are welcome — a TODO (per Benny’s note) marker is perfectly valid, as is TODO (Parramatta office), signalling that a particular concern originates from a specific field team or a specific audit window.

When the review wraps up, archiving the buffer with the change request provides long-term context. Months later, when a new analyst in Brisbane asks why a particular module behaves a certain way, the archived review file reads like a short story of the decisions that shaped the code. HydePark Consulting has long encouraged this habit because it pays dividends during staff handovers and during the twice-yearly compliance audits common in Australian infrastructure projects, where reviewers are expected to analyse every behavioural change in the network model and demonstrate that it has a documented trail.

---

If a deeper, hands-on walk-through would help, HydePark Consulting offers targeted sessions for Smallworld teams across Australia — from a one-hour pairing session in Melbourne’s CBD to a half-day workshop in your Sydney office. Reach out through the contact page and we will tailor a session around your current code base, your team’s reviewing habits, and the way your Git workflow is set up.