Magik Code Review Workflow with Emacs Diff and Ediff

Code review sits at the heart of every reliable Smallworld deployment. When teams ship changes to a Magik session manager, a property class, or a network analysis routine, the difference between a smooth release and a late-night rollback often comes down to how carefully the changeset was scrutinised. A disciplined review protects the integrity of the GIS, the utility network model, and the millions of records that customers rely on.

Emacs has been the editor of choice for many Smallworld consultants in Australia since the late 1990s. The same environment that lets you jump to a method definition or inspect a Magik object also handles version control diffs and merge conflicts with precision. A reviewer can stay inside a single frame, bouncing between a diff buffer, an Ediff control window, and the actual Magik source, without ever touching a mouse.

The diff and Ediff machinery in Emacs has matured over decades and remains one of the most underrated productivity tools available to Magik programmers. Out of the box, Emacs understands several version control backends, exposes hunks through magit-style interfaces, and provides a fully interactive side-by-side merge tool that handles every flavour of whitespace change. With a small amount of configuration, the same tools can highlight Magik comments, colourise slot definitions, and call out references to sw_product! with a distinctive style.

This walkthrough takes you through a practical review workflow that a Magik developer in Melbourne, Sydney, or Perth can adopt on Monday morning. The approach assumes you are already running a recent GNU Emacs connected to a Subversion, Git, or Perforce repository, and that you have access to a Smallworld environment for spot-checking compiled behaviour. Along the way, the article touches on local realities that shape how Australian Magik teams collaborate, from time zones to the consulting culture surrounding the utilities and mining sectors.

Preparing your Emacs build for Magik review work

Before the first diff is generated, it pays to spend ten minutes tuning the editor so it behaves predictably when the patches start flowing. Most Magik teams in Australia still run GNU Emacs 27 or 28 on either Windows 10 workstations or a Linux VM bridged into a Smallworld session. A shared configuration file under version control lets everyone benefit from the same setup.

The first item worth adding is the Magik mode hook that loads whenever you open a .magik file. Inside that hook, call magik-mode-init from the magik-mode package and then push Ediff-related key bindings onto the local map. A second piece of housekeeping is whitespace handling. Magik uses two-space indentation in most codebases, although some teams in Brisbane and Adelaide have standardised on four spaces. Set whitespace-style to include tabs, trailing whitespace, and lines longer than 100 columns, then enable whitespace-cleanup before save. Ediff will then highlight stray tabs in red and force the reviewer to resolve whitespace disagreements before reaching the method body.

Finally, configure your diff command so Emacs knows how to invoke it. Under Tools -> Compare (Ediff) -> On the fly, point the diff-program variable at the executable your repository expects. For Git the default is git diff, but for Perforce repositories used by larger utilities, you may need to wrap p4 diff -du in a small shell script. Run a sanity check by opening two revisions of a small Magik file and confirming that Ediff launches with a split window and a control panel.

Generating and reading diffs in the local context

The simplest way to begin a review is to produce a unified diff and load it into a buffer. From a terminal in Adelaide, Hobart, or anywhere else, run git diff main..feature/magik-utility-fix and capture the output with C-x C-w into a buffer named review.diff. Visiting that buffer with diff-mode gives you syntax highlighting, hunk navigation with M-n and M-p, and the ability to apply or reverse individual hunks with C-c C-a or C-c C-r.

For a deeper look, Ediff offers far more than a static read. With the diff buffer on screen, position the point inside a hunk and call M-x ediff-patch-buffer. A new frame opens, presenting the old and new versions of the file side by side, with a small control panel that lets you step through changes with n and p. The keyboard-driven nature of Ediff is valuable because you can keep your hands on the home row while flicking through hunks. The mode line shows the current difference number, the total count, and the number of regions that still require manual attention.

Australian reviewers also appreciate the way Ediff handles long method bodies. When a hunk spans more than thirty lines, the session splits into separate buffers with synchronised scrolling. Press j or k to jump to the next region, and use } or { to copy a region from the new file into the old one. If a Magik developer has reordered two private methods without changing their content, Ediff detects the similarity and offers a suggested match, saving the reviewer the chore of comparing them line by line.

Navigating method and slot changes with refinement

Once the basics feel comfortable, it is time to layer in tools that respect the shape of Magik source code. A method declaration starts with _method or _private _method and is followed by a target, a name, and a parameter list. The diff itself shows you the raw text, but a useful enhancement is to use a Magik-aware imenu so Ediff can jump between methods. Add (setq imenu-generic-expression magik-imenu-patterns) to your init file and call M-x imenu-add-menubar-index while inside a Magik buffer. When Ediff presents a long class with twenty methods, you can use the speedbar to scroll directly to the change that interests you.

For very large classes, consider binding ediff-revision to a custom function that compares the same method across two revisions. Many Australian Smallworld consultancies operate on the principle that a method should fit on a single screen, so reviewers often ask the author to split a long _method into smaller helpers. Ediff's region-highlighting helps here: mark a single _method with C-M-h, then call M-x ediff-regions-wordwise to compare just that block against its previous version. The output is far easier to read than scrolling through a 500-line class file.

It is also worth configuring a hook that detects new slot definitions. Add the following snippet to your magik-mode-hook:

(add-hook 'magik-mode-hook (lambda () (font-lock-add-keywords nil '(("^\s-*_pragma!\|slot\s-+" . font-lock-warning-face)))))

With that in place, diff-mode tints any new or removed slot with the warning face, making it obvious when a patch has altered the data model of a sw_product!. Reviewers in the water and gas sectors have reported that this single change has caught several regressions where an object upgrade was missed.

Whitespace, encoding, and edge cases

Magik files are usually saved in UTF-8 or ISO-8859-1, depending on the heritage of the codebase. Utilities in the Pilbara that ingest survey data from older mining systems sometimes still carry Latin-1 strings with diacritics, while a greenfield deployment in a Sydney water utility might be entirely UTF-8. Diff and Ediff can both become confused when two revisions disagree on encoding, so it pays to normalise the files before review. A simple preprocessing step is to run iconv -f UTF-8 -t UTF-8//IGNORE on each file, which strips invalid sequences and lets Ediff compare them cleanly.

Whitespace is the other classic source of review friction. Australian Magik teams have a healthy disagreement about tabs versus spaces, about trailing newlines, and about the placement of the trailing comment that some developers add after every _endmethod. Configure diff-refine to highlight changes on a character-by-character basis, and bind it to a key for the duration of the session. With refinement turned on, a renamed variable inside a long expression becomes a coloured block rather than a deleted-and-inserted line, which is much easier to verify.

Another habit worth adopting is the use of fringe indicators. The package diff-hl overlays arrows in the left fringe to show which lines have been added, changed, or removed in the current buffer. When you scroll through a Magik file freshly loaded from Git, the fringe tells you at a glance which methods have been touched since the last commit. This is helpful during a review meeting, where the reviewer can walk the author through the changes without losing their place.

Reviewing object database and collection differences

Magik's smallworld_product_database and the sw_db! machinery it uses present a different review challenge: the change might not be in source code at all, but in a data definition file or a collection schema. Reviewers at firms that work with SA Power Networks or APA Group frequently encounter patches that add a new field to a sw_collection! or modify a data sharing rule. Such changes need to be reviewed in a way that connects the source file to the runtime database.

A practical approach is to use Ediff alongside the Smallworld session manager. Open a Magik buffer that calls sw_product! and load the two revisions of the associated definition file. With Ediff in control, you can step through the changes while a Magik REPL in another window queries the live database with .show or .print methods. When the diff shows a renamed slot, you can immediately check whether existing data would still load. This kind of cross-tool review is far more thorough than a static text comparison and has caught several migration errors in Australian deployments over the years.

For very large collection differences, consider exporting both revisions to CSV and using Ediff on the resulting files. The diff will be line-oriented and easy to navigate, and you can use the regular Ediff key bindings to step through additions and removals. Pair this with a small Magik script that prints the row count for each side so the reviewer can confirm the totals match expectations before looking at content.

Collaborating across time zones and patch cycles

Australian Magik teams are rarely all in one office. A typical project might pair a developer in Melbourne with a reviewer in Perth, three hours behind, or have colleagues in Darwin joining the standup at eight in the morning. That distributed reality shapes how reviews are scheduled and how notes are captured. The most common pattern is asynchronous: the author pushes a changeset, the reviewer works through it during their morning, and the comments are left in the issue tracker.

Ediff fits this pattern well because the reviewer can record their thoughts directly in the diff buffer. Use M-x diff-add-log-current-entry to insert a comment header that captures the change, then use C-c C-c to mark the current hunk as accepted, C-c C-r to reject it, or C-c C-b to leave it for the author to address. The buffer can then be saved to disk and emailed or attached to the review ticket, giving the author an exact record of what was discussed.

For teams that prefer real-time sessions, a shared SSH session into a development box in Mascot or Clayton works well. The reviewer and the author can drive Ediff together, with one person stepping through hunks while the other explains intent. A flat white from the kitchen and a quick chat about the weekend is usually enough to break the ice before the technical review begins, and the Ediff control panel keeps the conversation grounded in the actual lines being discussed. The result is a shorter review cycle, a more honest conversation about the code, and a higher-quality patch that lands in the main branch on the first try.

Subscribe to the Magik Emacs newsletter for more workflow tips, and download the magik-ediff-setup package from the HydePark Consulting repository to get started with the configuration shown in this article. If your team needs a hand tailoring a review process for a Smallworld deployment, get in touch with HydePark Consulting to arrange a workshop.