DEV Community: Benjamin Muskalla

Git Archeology

Benjamin Muskalla — Tue, 12 Jan 2021 00:00:00 +0000

Working on a large codebase, it’s pretty normal to not remember every small or large subsystem or implementation choice. Be it whether you’re new to a codebase, or you’ve been focussed on a specific area of the codebase. When working on refactorings or bug fixes, I often end up in areas I might not be too familiar with. Generally not dramatic, it happens quite often that I’m stopping at what I’m doing because I need to decide on how to move forward. As software engineers, we have to make so many micro-decisions every minute that we’re pretty used to it. Depending on the code and domain knowledge, we often find ourselves in situations where we need more context to make an informed decision. Tests usually provide a pretty good context but depending on their granularity and naming, they might only tell is “what” is in the implementation but miss the “why”. And if we try to decide whether we can remove a certain check or rework a behavior, we need to understand why it was introduced in the first place. Usually, we resort to looking at the commit that introduced the change or the tickets associated with the commit.

Most people will start with using git blame (or the respective functionality within their IDE/editor). But on most non-trivial projects, you usually end up with a refactoring commit, a rename, or a trivial cross-project fix like switching to another assertion library. At first glance, we only see the most recent changes, not the most important ones. We need to carefully remove layer by layer of sand and dirt that has been swept over the real changes to unearth them.

Moving Backwards In Time

A simple git blame shows us only the most recernt changes. Assuming it’s a simple move within the file or a whitespace fix, we can ignore those using the flags that git blame offer us:

-w: ignores whitespace changes
-M: ignores changes if the line was just moved/copied within the same file
-C: ignores changes if the line was just moved/coped from other files

The above flags are already useful. Most of them are not only available on the command line though, they’re usually available in the various editors as well (feel free to show how it’s done in your editor and share on Twitter).

Usually, this allows to hide some of the more trivial commits but requires git to detect them as such. More often, we (as engineers) can easily gauge whether a commit is relevant for our search based on commit message, author, and coding practices. Luckily, this can also easily be achieved by the various editors by moving backward commit-wise. Looking at the history on GitHub, you can use the “View blame prior to this change” feature:

Similarly, IntelliJ-based IDEs allow you to do the same using “Annotate Previous Revision”:

In case you’re using Visual Studio Code, the excellent “GitLense” extension offers similar commands:

Moving Forward

Depending on what we’re looking for, we may not want to uncover commit by commit until we find the initial commit that introduced something. Let’s say that we’re working with a customer who sees a specific error message on an older version of our product. On main, this error message is not present anymore as somebody refactored the code already. To dig into this, we’ll have to find out when this error message got introduced. One way to pick through the whole history in the search for the holy grail..err..the error message is to use git pickaxe. Pickaxe is part of git log can be used as follows

git log -S'errorMessage'

By default, it will spit out all commits that introdcued or removed the the string errorMessage in any way.Especially with error messages, you may be looking for an error message template that has variables in there. Luckily, git has us covered: you can use --pickaxe-regex and use -S<regexp> to find matching commits. Be aware that using -S will only find commits that change the number of times a string is found (addition/deletion). If you’re also looking for a commit that changed the position of a string (e.g. a refactoring that moved the keyword around), you are better of using the -G:

git log -G"error.*"

Skipping History

Whether you move forward or backward through history, there will always be the “big bang” refactorings that get in your way. Be it that your team decided to agree on certain line endings, a large split of the codebase or a rename to align the codebase with the ubiquitous language. So these changes are usually never interesting in the context of wading through the history for a specific line and Git has some neat features that allow us to skip those when looking at git blame for a file. The simple approach is to pass all commit ids that we want to ignore using --ignore-rev as the following example shows. Given this history for a file, consisting of the important change as well as a commit that just refactored the file:

❯ git log
commit 301b7eca0eb57737e160f5d2d16208f65c4156d6 (HEAD -> master)
Author: Benjamin Muskalla <bmuskalla@gradle.com>
Date: Tue Jan 12 11:38:40 2021 +0100

    Reformat all source files

commit bd3fca50ee1659e740e2f6744d95e737418f1f40
Author: Benjamin Muskalla <bmuskalla@gradle.com>
Date: Tue Jan 12 11:38:12 2021 +0100

    Important change

As expected, regular git blame shows the most recent changes on the file. This is the commit reformatting the file which is irrelevant for us. We want to see an important change.

❯ git blame sourcefile.py
301b7eca 1) import random
301b7eca 2)
301b7eca 3) print(random.randint(0,9))
301b7eca 4)

So using the “ignore revisions” feature allows us to explicitly ignore specific commits, thus showing us the commit we’re interested in:

git blame --ignore-rev 301b7ec sourcefile.py
^bd3fca5 1) import random
301b7eca 2)
^bd3fca5 3) print(random.randint(0,9))
301b7eca 4)

Throughout the lifetime of a project, this approach certainly doesn’t scale. There will always be commits that should be ignored in those cases. Based on the same approach, git blame allows you to specify a file that contains a list of commits to be ignored. This is not only handy as you can check it in with all your other files, but it’s also easy to share this within your team so everybody can leverage this as well. In our example, let’s call it .git-blame-ignored-revs and specify which commits should be ignored using their commit hash. You can use # to add comments to the file as well.

# ignore pure formatting commits
301b7eca0eb57737e160f5d2d16208f65c4156d6

You can now manually use this file as your source of filters using --ignore-revs-file.

❯ git blame -s --ignore-revs-file=.git-blame-ignored-revs sourcefile.py

If you want this to be the default behavior, you can either create a git alias for this or even configure git to always use this file. With this configuration, git blame will always ignore the commits in .git-blame-ignored-revs:

❯ git config blame.ignoreRevsFile .git-blame-ignored-revs

A nice side-effect of using git config is that other tools and editors that rely on the command line tools behaviour just fall in line with these settings. For example, IntelliJ IDEA shows the “Important Change” when enabling annotations:

Recap

Different problems require different approaches. Whether you’re looking for an error message that is long gone from the main branch or try to peel back the layers for some new code, git offers a tremendous amount of tools for your needs. Sometimes it is enough to remember that certain tools or approaches exist so you can look them up if you decide which way you want to approach your search:

git blame with its various filters like -M
git log -S/-G to look for additions/deletions for specific keywords or patterns
git blame --ignore-rev to hide known, noisy commits

I hope I was able to show the one or other interesting bit that can you add to your own toolbox and would be happy to hear about your approach to software archeology.

JIT 101

Benjamin Muskalla — Mon, 11 Jan 2021 20:19:08 +0000

JIT compilation and HotSpot are with no doubt some very complex topics. This blog is a very short article touching on the topic in question; it was originally intended to be included in 97 Things Every Java Programmer Should Know. Contributions for the book had a limit on its length, thus a very short introduction into the HotSpot JIT. In the end, the book authors choose another piece of mine to be included but I thought this might be interesting for the one or other person out there.

Compared to other compilers, javac avoids a lot of optimizations when compiling java source code to bytecode. While “Ahead-Of-Time” (AOT) compilation
can do more heavyweight analysis of the source code, a dynamic compiler can take into account runtime statistics like the most used paths (hotspots)
and advanced chipset features (e.g. which CPU instruction sets are available).

Enter the “Just-In-Time” (JIT) compiler. That means over time, the behavior of what and how to compile bytecode to native code changes. Initially, most
bytecode is actually just interpreted (tier 0) which is rather slow. Once a code path is “hot” enough, C1 compiler kicks in (most of us know this by
the -client flag). It is not as aggressive and allows for a faster initial startup. The C2 compiler (-server) uses more comprehensive analysis and is
meant for long-running processes. Since Java 7, the JVM uses a compilation mode called tiered compilation which seamlessly switches between the modes
based on application behavior.

Initially, the compilers insert profiling probes into the bytecode to determine which code paths are the hottest (e.g. by invocation count), invariants
(which types are actually used), and branch prediction. Once enough analytics are collected, the compilers actually start to compile bytecode to native
code once they are “hot enough” (-XX:CompileThreshold), replacing the existing byte code step by step (mixed mode execution).

Starting with the hot path, one of the first things the compiler tries to achieve is constant folding. Using partial evaluation and escape analysis,
the compiler will try to determine if certain constructs can be reduced to constants (e.g. the expression 3 * 5 can be replaced with 15). Another
rather simple optimization is to avoid method calls by inlining methods into their call sites (if they are small enough).

Virtual method calls present a more complex problem. Generally, the best case is a monomorphic call, a method call that can be translated to a direct
jump in assembly. Compare that to polymorphic calls, like an instance method whose type is not known in advance. The type invariants collected previously
by the probes can help tremendously to identify which types are most often encountered within a code path.

The compiler optimizes aggressively using heuristics as well. In case a guess was actually wrong (e.g. the seemingly unused branch was called at some
point), the compiler will deoptimize the code again and may revisit this path later using more profiling data.

Depending on the architecture the JVM is running on, the bytecode may not even be used at all. The HotSpot JVM uses a concept called "intrinsics"
which is a list of well-known methods that will be replaced with specific assembler instructions known to be fast. Good examples are the methods in
java.lang.Math, System#arraycopy or Object#getClass (see @HotSpotIntrinsicCandidate). For a more in-depth explanation of instrinsics, I can highly recommend this article

Multi-threaded applications may as well benefit from the optimizations the JIT can do with synchronization locks. Depending on the locks used, the compiler may merge synchronized blocks together (Lock Coarsening) or even remove them completely if escape analysis determines that nobody else
can lock on those objects (Lock Elision).

You can enable a lot of debug information about how the compiler decides what to do with your code using feature flags like
-XX:+UnlockDiagnosticVMOptions -XX:+PrintInlining. If you want to dive deeper into the world of the Hotspot JIT Compiler, have a look at JITWatch.

To have a real deep-dive into such topics, I can highly recommend the posts by Aleksey Shipilëv.

Java Syntax Puzzlers

Benjamin Muskalla — Mon, 11 Jan 2021 11:43:19 +0000

Roughly 12 years ago, I started to contribute to the Eclipse ecosystem in various functions. One of the most interesting experiences to this date was to work on developer tooling and handling the edge cases so others don’t have to struggle. Though I stepped down as an Eclipse committer in the meantime, I’m still attached to working on productivity tooling nowadays as a member of the Gradle Build Tool.

While working on Eclipse, I fondly remember working on various parts of the Java Tooling (JDT) and while working on refactorings and quick fixes. And not surprisingly, working on language-intensive pieces turned out to have the same hiccups as other non-trivial algorithsm - the transition from “this is gonna be easy” to “why am I up at 3am reading the Java Language Specification”.

Opening a bug report with snippet to reproduce: 10min. Working on a patch: 2h. Getting pinged whether you can finish that patch, 11 years later: priceless. I do miss working on #eclipse #jdt though https://t.co/vpLD73zOlC
— Benjamin Muskalla (@bmuskalla) March 27, 2019

Working on language-specific tooling exposes you to all kinds of edge cases and delicate details and language has to offer. Some of them are well known and generally seen "unprofessional" (hello goto). Others are actually not known at all. And with all due respect, I quite enjoy discovering the edge cases of the language syntax - a lot of times to confuse my co-workers who think they know the Java Language Syntax ;) And given I love a good puzzle (especially the Java Puzzles), let’s try a puzzle but using the Java syntax only, without any runtime behavior.

Using Java for Phishing

Let us start off with a widely known fact about Java source files. You’re allowed to use Unicode in most places of your code. While we can’t use the full range of unicode in your class names (I still want to write throw 🎂()), you can add enough Unicode to play some pranks on your co-workers.

As an appetizer, in your next (remote) pairing session, just slip in a “Greek Question Mark” (U+037E) into the code and watch your co-worker trying to find out what is wrong with that simple semicolon. This technique is most often used by phishing emails to make a URL look like the real one but actually points to a very different domain.

As it doesn’t even compile, that’s an easy one for your co-worker to recognize and fix. Let’s start to be a little more sneaky.

Guess what the following program prints?

public static void main(String[] args) {
    if (1 == 2) { // one down, one to go: \u000a\u007d\u007b
        System.out.println("1 is 2");
    }
}

Yes, in the context of the post, you correctly guessed that it is printing “1 is 2”. Just...HOW? How is it possible to trick Java into thinking 1 == 2, even with unicode magic. INSIDE A COMMENT. Any guesses? It actually doesn’t change the expression. The following unicode characters were harmed in the process:

\u000a - the newline character \n
\u007d - a closing curly brace }
\u007b - an opening curly brace {

So the code we’re actually looking at is this:

public static void main(String[] args) {
   if (1 == 2) {
   }
   {
       System.out.println("1 is 2");
   }
}

Funny enough, most programmers would suspect something fishy with this comment when they see it. But what about indenting it so it’s not shown in your editor anymore? ;)

Blocks of Blocks

Let’s move on to the Java Language Specification and see what interesting bits of syntax we can find in there.

Looking at the possibilities we have for implementing methods, Java defines method bodys to contain Block elements:

MethodBody:
  Block

Block:
  { [BlockStatements] }

BlockStatement:
  LocalVariableDeclarationStatement
  ClassDeclaration
  Statement

Taking a closer look at the definition of Block, we learn that they can contain statements (so far so good) but also…ClassDeclarations. Now it gets interesting. Let’s see how deep the rabbit hole goes.

public void howDeepCanWeGo() {
    class Foo {
        public void hello() {
            class Bar {
                public void helloFromBar() {
                    // You musn't be afraid to dream a little bigger, darling.
                } 
            }
            new Bar().helloFromBar();
        }
    }
    final Foo instance = new Foo();
    instance.hello();
}

Funnily enough, while this feature seems quite useless at first sight, it’s the only one I’ve been using in actual test code in the past. While working on a framework that heavily relied on reflection, the inline class definitions came in quite handy to define classes under test and keeping them with the test. The alternative of having a bunch of nested classes scattered alongside tests was a good reason to move them closer to the test. You can read me more about the quirks of local classes in JLS 14.3.

This and That

Moving away from classes and closer to the action. Let’s have a look at method parameters. As you may encounter several times yourself, you can’t name things the same as keywords. Well, let’s have a look at the following snippet.

public class KeywordParameter {

    public static void main(String[] args) {
        KeywordParameter someObject = new KeywordParameter();
        someObject.callMe(3);
    }
    public void callMe(KeywordParameter this, int foo) {
        // ...
    }

}

So we’re creating a new instance of KeywordParameter and calling the callMe method on it. Passing the int parameter. But wait, the method has two parameters. And one is even named after a keyword. That shouldn’t even compile, right? It actually does. Looking at the JLS 8.4 Method Declarations, we can find the definition for method declarations.

MethodDeclarator:
  Identifier ( [ReceiverParameter ,] [FormalParameterList] ) [Dims]

We see that the first parameter is a special, optional parameter not part of the formal parameter list. And it’s actually defined to always have the name “this:

ReceiverParameter:
  {Annotation} UnannType [Identifier .] this

The so-called “receiver parameter” is an “optional syntactic device” that represents the object it is invoked on (so it’s really the same as what you’d expect from “this”). Its sole purpose is to be available in the source code to be annotated if necessary. Let’s assume we have an @Immutable annotation in our project and for some reason, we want to ensure that our IDE (or other code analyzers) understand that this in our current context represents an immutable data structure. With the explicit receiver parameter, we can annotate it correspondingly:

    public void callMe(@Immutable KeywordParameter this, int foo) { ... }

@Everywhere

Talking about annotating things for the purposes of analyzing code. For the above snippets to work, the annotation needs to be targetable for PARAMETER. Did you ever look up what other targets an annotation can have? Going through the most common ones, there are no surprises:
TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, ANNOTATION_TYPE, PACKAGE, TYPE_PARAMETER, MODULE (since Java 9) and RECORD_COMPONENT (since Java 14). But there is one that’s not so obvious where to put it: TYPE_USE. From the name, it sounds like it can be used everywhere a type is used. Let’s try and use it in some places:

@TypeAnnotationsEverywhere.Immutable // ok, easy, similar to TYPE 
public class TypeAnnotationsEverywhere {

  public void giveMeMoreTypes() throws @Immutable RuntimeException {  // errr what?
     Object foo = new @Immutable Object(); // WHAT??????
  }

  class Foo implements @Immutable Function { ... }

}

Indeed, using TYPE_USE allows us to put the annotation in the most unusual spots. JLS 4.11 defines all the spots that are covered by a “type usage”.

Which one of those syntaxes were you aware of? Got all of them? The code for the post can be found on GitHub as well. In the meantime, I’m still working on my museum of interesting cases of the language constructs, so please share anything you’ve encountered yourself. You can reach me on Twitter via @bmuskalla.

Refactoring towards speed reading

Benjamin Muskalla — Tue, 05 Jan 2021 13:56:43 +0000

When was the last time you were in the flow while working through some code? Reading code or doing code reviews is an activity that we do often, yet we don’t often get into the zone doing it. Too many times, we have to slow down, check that last line again or try to figure out the structure of the code. Even though we all follow the same principles for clean code, there is always that gut feel which tells you that one style is better than the other. While not conclusive, a part of this is the way we structure code for readability.

Speed reading is a technique many people have heard about. The casual reader usually reaches 150–200wpm (words per minute) with a good comprehension rate. Auditory readers can read approximatly 400wpm while visual readers can reach up to 700wpm. Controversial world record holders in speed reading claim to reach up to 4200wpm. But don’t worry, we don’t need to set the new world record in speed reading to learn the basic concepts and apply them to another area: our code. We’ll look at 3 areas that are particular helpful when it comes to reading code: Skimming, meta guiding and visual fixation.

So what makes speed reading that fast? One of the first steps is to suppress subvocalication. Subvocalization? Exactly. That voice in your head that just tried to properly articulate that word. And yes, you’re now aware of that voice again. But don’t worry, it will be gone soon :) Subvocalization is something that an adult should be able to learn with relative ease as a first step to seriously improve reading speed, not only for code.

In this post, I’m not going into the details of learning to speed read as others do a way better job at that. Be it books, articles or software like spreeder or spritz.

Lets get to our first example that we want to refactor to improve readability. Here is a simple function which takes 3 parameters.

I suspect it is not the first time for you reading code so I can safely assume that you didn’t even try to read it word by word. The first thing that happens when trying to read this code is that we try to skim over it and find the relevant bits of what is happening based our previous expierence. One likely way to read the code is to follow where and how the input parameters are used. Using eye tracking, what was likely happening when you read the code is this eye movement:

After locating name, we actually have to break our visual fixation and find the next parameter which requires us to look down and left. We can start with a very simple refactoring to help a bit with this:

Better. But we’re not there yet. Looking at the semantic meaning of the three lines of code here suggests that they’re in fact not too different. We do validate all three arguments, not just age as the method name suggests. While many people these days strive for clean code, the trigger to extract a method is usually the number of lines that can be extracted. By extracting methods for these cases even helps us to guide the eye, allowing future engineers to actually skim over the code and let them decide whether they need to stop here or actually go on depending on what they’re looking for.

By the way, were you able to read the animated sentence in orange above? That was 400wpm. That is already very fast. The fact that we can rely on visual fixation to avoid additional eye movement helps us to keep up. If you’re not used to this reading speed, comprehension usually suffers when reading a longer text in that speed. You can usually try it with speed reading apps, browser extensions or this bookmarklet if you’re curious.

Meta guiding is another principle in speed reading that is commonly suggested when starting to learn speed reading. Instead of trying to read word by word in a book, you try to capture the whole line at once. Kids usually do that by using their finger to keep track of the word they’re reading. As adults, we usually stopped doing that at some point. But using a finger or another device helps us to keep moving forward and avoids jumping back a word or two. Funny enough, code itself can act as such a device as it has an inherit structure that we can leverage to guide our eye.

How many items are in the list? One, two, three, four! Five. Maybe more. Oops, missed that zeros argument, too?. The structure that should actually help us gets in our way. While we have allowed our “reader” to be guided by the alignment of the add methods, we totally misguided the eye and missed the constructor argument. Rewriting this to match the pattern of the other add calls allows the reader to follow the guide easily without missing any important information.

Now all the methods that actually add something to the list are in line and easy to spot without looking back and forth.

What are your code snippets that you broke your flow of reading in the past? Because most of the time, parsing the code with our eyes is what we do. The trick is not to become a better parser or a better reader. The goal should be to write our code in a way that it helps guide the reader towards the important aspects of the code. A reader needs to be able to skim over the code, ignore the boilerplate that does not add to the semantic understanding and still have a high comprehension. But in the end, it goes a long way to write code that is not only readable but can actually be digested in a really fast manner.

Next time you write some piece of code, see if you can actually speed read it.

Cover Photo by Fischer Twins on Unsplash

Merging nested Lists or Arrays with Java 8

Benjamin Muskalla — Tue, 15 Nov 2016 00:00:00 +0000

When accessing 3rd party APIs with pagination, we tend to see the same pattern over and over again. Usually, a response (represented as POJO) looks something like this:

class Result {
  public List<Item> getItems() {
    ...
  }
}

Be it from a third party service or your own APIs, after retrieving all results of the API call, we end up with something like a List<Result>. Great. We don’t really care about the response itself, we’re actually interested in all the items of the responses. Let’s say we want all the items, filter some of them out and transform them into a TransformedItem. People usually start writing something like the following:

List<Result> results = ...
List<TransformedItem> newItems = results.stream()
     .map(result -> result.getItems())
     .filter(item -> item.isValid())
     .map(TransformedItem::new)
     .collect(toList());

Ooops, this doesn’t even compile. The problem is that the first map doesn’t return a Stream<Item> but actually a Stream<List<Item>>. In order to actually merge/flatten all those nested lists, you can use Stream#flatMap. The difference is quite simple. #map allows you to transform an element in the stream into another element. On the other hand, #flatMap allows you to convert a single element to many (or no) elements.

List<Result> results = ...
List<TransformedItem> newItems = results.stream()
     .map(result -> result.getItems())
     .flatMap(List::stream)
     .map(TransformedItem::new)
     .collect(toList());

Just in case you’re working with a 3rd party API that returns something ugly as List<Item[]>, you can use the same pattern, just choose the corresponding the flatMap function.

class QueryResponse {
  public Item[] getItems() {
    ...
  }
}

...

List<TransformedItem> newItems = results.stream()
     .map(result -> result.getItems())
     .flatMap(Arrays::stream)
     .map(TransformedItem::new)
     .collect(toList());

Have fun with #flatMap and let me know on Twitter how you used #flatMap in your scenarios. A great explanation of how to compose streams and some concepts behind streams can be found in Martin Fowler Collection Pipeline.

WHERE_TO_PUT.CONSTANTS

Benjamin Muskalla — Thu, 06 Oct 2016 00:00:00 +0000

When writing software, some conversations happen over and over again. Over the years, I’ve seen different solutions to the same problem that I’d like to share with you. One of those conversations go something like this, even though the answer might differ depending on the team or component.

Bob: Hey, I have some string literals here and I was told in the code review that I should extract those into constants. But where would I put those?

Alice: Ah, sure. Just put them into our MyModuleConstants class. We put all constants into that class so they are easy to find.

public class MyConstants {

  public static final String V0 = "v0";

  public static final String LABEL_STATUS_OPEN = "Open";

  public static final String UNUSED = "butNobodyWillKnow";

  public static final Long MAX_SIZE = 13498368L;

}

Soooo. Constant classes, eh? Let me share some of the patterns I’ve found (and used myself) over the years and see if we can somehow adapt or improve existing patterns when and how to use constants…and when not to. Take it a bit like “Refactoring away from constants”. First things first, I’m not going to talk about constant interfaces here. Please refer to Item 17: Use interfaces only to define types why that’s a bad idea.

First up, naming constants. Easy, right? Not at all. It’s as hard as naming classes and methods to make the intention really clear. Otherwise, Bad Things™ will happen. Let’s take a look at our first constant.

public static final String V0 = "v0";

It seems to be defining some kind of version number. Let’s assume our project is interacting with a 3rd party API, this seems to be the version number of their REST API. Now, taking a step back, why do we extract constants in the first place? Usually, it’s for two reasons:

To make the intention of a value clear (magic numbers as one example)
To make the code easier to maintain by factoring out common constants so they can be easily changed in the future

For the above example, the intention is not clear at all. While we can guess it’s a version string, we don’t know how it is supposed to be used. Is it so all API calls use the same version of the REST API? Or is it to determine whether we’re working with the v0 version which requires some special handling? If we now want to upgrade to v1 of the REST API, it’s not as easy as just changing the constant as other code might rely on this exact version. Without proper naming, people tend to reuse constants for different scenarios that actually require two different constructs (which might happen to have the same value for now). Assuming we had the two scenarios above, we slightly better way would be

public static final String REST_API_V0 = "v0";

public static final String REST_API_CURRENT = V0;

Not really great either. We still try to group out constants together using a common prefix (REST_API). Usually when you start using common prefixes, that group usually shares some kind of responsibility (see also this paper and a research prototype for an automated refactoring). Let’s try and extract these constants out into their own entity.

public enum RestApiVersion {

  V0("v0"),

  V1("v1");

  private String apiPath;

  public static RestApiVersion getCurrentApiVersion() {
    return V1;
  }

  private RestApiVersion(String version) {
    this.apiPath = version;
  }

  private String getApiPath() {
    return apiPath;
  }

}

I think the main takeaway from this is that people tend to mix up literals and magic numbers. While everyone is trying to follow the “Extract magic numbers into constants” refactoring, they tend to see every literal as “magic number”. Be aware of the fact that constants usually have no context and thus may form cohesion where none exists. The example doesn’t cover the full story though. One nice side-effect is that we gain compile-safety by using a proper type (be it an enum or a class with the strategy pattern). While enums are usually preferred over constants, take a step back and see if there is even a need for a “list of constant things” or if a higher abstraction actually makes more sense. For example, if there is a need to dynamically influence the current version (e.g. for testing/mocking) or if there is more to handling different versions, I recommend to check out the Strategy design pattern which I’ll leave as an exercise for the reader.

Defining constants by constants is another pattern I’ve seen quite a few times. Take the example above of the RestApiVersion. A slightly different incarnation I’ve seen many times is the following:

public enum RestApiVersion {

  V0(MyConstants.REST_VERSION_V0), // no, no, no

  ....
}

This again goes back to treating every literal as a magic string. There is no additional value gained by defining REST_VERSION_V0 as a separate constant. The opposite is actually true. How do consumers decide when to use the proper facade like RestApiVersion and when to use the “backdoor” by just using the REST_VERSION_V0 constant itself. With the constant exposed as a constant value, there is also no chance for the maintainer of RestApiVersion to dynamically adapt to future needs. With the whole concept modeled with a proper API, we do have a chance to change the implementation without breaking consumers.

Whenever you’re about to create a *Constants class, take a step back, go for a walk, or grab a coffee with a fellow engineer. Try to explain why you want to create such a class and if that is really the right abstraction or if the next engineers on your component might be able to see the patterns easier with another abstraction. There are a lot topics we haven’t touched on yet. When should we actually use constants? What about literals with placeholders (I look at you MessageFormat). And are there any tools to detect unused constants? Let me know in the comments.¹

Originally published on Tasktop Blog ↩︎