John McCarthy on source code presentation

John McCarthy (inventor of Lisp) in an interview by Guy Steele:

“A language should be designed in terms of an abstract syntax and it should have, perhaps, several forms of concrete syntax: One which is easy to write and maybe quite abbreviated; another which is good to look at and maybe quite fancy, but after all, the computer is going to produce it; and another, which is easy to make computers manipulate.”

I (this is not John McCarthy speaking now) think that the smaller, utility languages such as make, sed, awk, shell, and regular expressions could benefit hugely from an expanded, beginner-friendly representation. Many programmers need to read or maintain scripts using such languages, but not frequently enough (or with too little time) to justify learning those languages in depth.

Take makefiles. Useful annotations (and not just for beginners!) include:

• Syntax highlighting to distinguish targets from patterns and prerequisites.
• Syntax highlighting to distinguish variable references from the surrounding text: $Foo is the value of variable F followed by the text oo.
• Documentation of make functions (like patsubst), automatic variables ($@), and implicit variables (CFLAGS).¹
• Static analysis of the makefile to expand variable references, function calls, and recipe escaping, when possible.
• Recognition of common conventions: For example, the GNU conventions state that variables like CFLAGS and LDFLAGS are intended for users to override from the command-line.
• Recognition of common patterns, such as rules that extract dependency information from source files.

View an example of the above annotations.

¹: Note for Emacs users: If GNU make is correctly installed on your system, you can jump to the appropriate documentation for any of these with info-lookup-symbol (bound to C-h S). If Emacs prompts you for the help mode to use, type makefile-mode. If you’re not familiar with the Emacs info browser, all you need to know is: Space to scroll down, backspace to scroll up, and the usual search mechanisms (C-s) to search (after reaching the end of a node, pressing C-s again will continue searching in the rest of the manual).