When it comes to discussing keyword expansion, there are generally two camps — those who advocate the practice, perhaps out of tradition, and those who insist that the practice is unnecessary because the meta data is stored and available separately [example thread]. Most version control systems, including AccuRev, provide support for keyword expansion. But the real question is, “are there legitimate reasons for actually using keyword expansion?” Based on what I’ve seen in practice at various organizations, I’ll attempt to convince you of three and show you how to cleanly execute them within AccuRev (where applicable).

But first, the downsides of keyword expansion in general.

• False-positive merging – The underlying physical problem with keyword expansion is dealing with false-positive diffs and merges. For example, consider two programmers working in parallel on the same file. Both open the file, make no content changes, then each commit their file. The first person to commit, goes home. The second person is forced to perform a merge — not of content, but rather meta data like $Author:$, $Version:$, or $Id:$. Imagine the mess created when having to merge 10′s or 100′s of files. ick.
• Wading through Meta – Dealing with source code that’s embedded with 50-100 lines of commit history, especially at the top of the file, is a painful experience. In an era of practicing the art of self-documenting code, having pages of uncompilable text mottled in the view is frustrating. Imagine having a 15-page legal disclaimer at the head of each source file… it’s the same feeling.

Now, on to the good stuff!…. 3 reasons for Keyword Expansion.

• Managing source code as a product. $Id:$. If your deliverable is not a compiled binary or legally immutable executable but rather source code itself, the recipient may have the ability to modify, refactor, or extend the source (See my whitepaper on vendor code management). For example, consider a case where one company writes the core software logic for a chip, but the manufacturer has an agreement to modify and embed variants of the software into their custom chips. The manufacturer may completely mangle the original directory locations or rename the files… but having embedded meta data from expanded keywords helps the original author backtrace a problem to the exact version of the file resident in SCM. Within AccuRev, it’s recommended to perform keyword expansion at release time rather than during development. This way, developers only see the raw, non-expanded keywords day-to-day and the expansion happens at deployment time. See diagram for an example.
• Embedding compile-time version information. $Version:$. When a program is executing (binary or interpreted), it’s common for the user to ask, “What version am I using?” One way to supply a version (but maybe not the most elegant, especially for those in Marketing) is to embed a $Version$ keyword as a data value to a static or global variable (i.e. global VERSION=”$Version: $”). When the file is compiled, the executing program has runtime access to the value to display. See diagram for an example in Java.
• ‘Classic’ Code Reviews. $Log:$. For all those folks who still print out reams of paper and crowd around a conference room table, it’s helpful to have the last 10 or so commit logs in the file so you can blam… I mean, understand why changes were made. While this does hold some merit, the folks over at SmartBear have a code review solution that eliminates the need to embed meta data within source code for code reviews. Within AccuRev, I’d suggest embedding keywords but not expanding them from a development day-to-day. Rather, when it comes time for a code review, simply ‘pop’ (i.e. export) the code onto disk and perform a one-off expansion.

There may be a few more examples advocating a legitimate use of keyword expansion and I’ll add them to the list when they come up. I hope these examples are helpful.

/happy expanding/ – dave

• Previous Entry: Put your source code on a "Build Artifact" diet with AccuRev
• Next Entry: Agile Programmable Completion – AccuRev + GNU Bash