Add flair to your code: Code Squiggles

Wrought Iron by quadriremeFor several months now, I’m experimenting with a programming style that you might want to call “syntax aware programming”. Every coding step starts with the question “what do I want to achieve and how do I want to write it down?”. Then I proceed to write it down in this perfect manner, mostly some english sentence, and try to incrementally convert the syntax into something the java compiler stops complaining about. There’s a lot to be learnt about API design, naming and creative syntax usage this way. One thing I’ve discovered along the way are Code Squiggles.

Introduction to Code Squiggles

Code squiggles are little methods that contain no functionality, other than directly returning the single given parameter. Their purpose is to make the code more fluently readable by casual readers. Calling these methods is absolutely optional, as they offer no behaviour at runtime. But by bloating your code with these method calls, you lower the amount of syntax rules and conventions the reader has to know before being able to understand the code. The process of adding the method calls feels like adding “happy little squiggles” (I certainly miss Bob Ross!) to your code.

Adding Code Squiggles by example

Let me give you a full example how Code Squiggles can turn your boring old java code into something even non-programming readers can grasp without problems. Note that the process of transforming the code isn’t the process I initially described, but the way to deal with existing code.

The initial code fragment looks like this:

assertTrue(filesDirectory.getChild("0.png").isFile());

As you can see, it’s an assertion line of an unit test. We improve the readability by extracting the intent of the assertion into the called method name (it’s a normal “extract method” refactoring):

assertFileExists("0.png", filesDirectory);

Now is the time to add the first Code Squiggle:

assertFileExists("0.png", in(filesDirectory));

You’ve noticed the difference? It’s just the word “in”, but it improves the semantics of the second parameter. As I promised, Code Squiggles are methods without any functionality worth talking about:

protected VirtualFile in(VirtualFile filesDirectory) {
    return filesDirectory;
}

The method takes a parameter and returns it. The real “functionality” of this method lies within its name. Everything else is only necessary to overcome (or overcode) java’s shortcoming of advanced syntax definition measures.

That’s all about Code Squiggles. But it doesn’t stop here. Let’s improve the example to its final shape, when we add two squiggles:

assertFile(withName("0.png"), existsIn(filesDirectory));

Read this line out loud! And notice the subtle change in the assertion method’s name. It begins to deminish clarity without the Code Squiggles. That’s when your API begins to depend on them. But it’s still perfectly valid java code if you just omit them.

The conceptual origin of Code Squiggles clearly comes from the behaviour driven development (BDD) style of writing tests and the ScalaTest Matchers. So I can’t claim much originality or cleverness myself here. But Code Squiggles, despite this initial example, aren’t limited to test code.

Adding inline documentation with Code Squiggles

Remember the last time you needed to integrate an horrible third-party API? Probably, there was a method with seven or eight parameters and all of them were primitive ints. No matter how often you called this method, you couldn’t remember the order of these ints. That’s when Code Squiggles might help you a bit.

This is the signature of a fairly complex method:

protected int performCalculation(int value, int lowerLimit, int upperLimit, int offset) { ...

Therefore, your call isn’t very self-explanatory:

int result = performCalculation(10, 2, 23, 13);

But it might be a lot more understandable when you add some squiggles:

int result = performCalculation(value(10), lowerLimit(2), upperLimit(23), offset(13));

I won’t spell out the squiggle implementations, as they should be straight-forward. Note that the java compiler doesn’t catch up here. You can easily swap the squiggles around to obfuscate your code. All you got is read-time safety. If you want compile-time safety, you need to replace the primitives with types and probably pay for some rounds of beer for the third-party API developers to include your changes or write an adapter (“corruption layer” is my preferred term here).

Regular use of Code Squiggles

If you want to use squiggles a lot, you might think about collecting them in a dedicated class. Design them to be static and generic, and you can use them easily with static imports:

public static <T> T existsIn(T instance) {
    return instance;
}

But remember that there are reserved keywords in java that might hamper you a bit.

Conclusion

Code Squiggles are useless bloat to your code unless you value read-time safety or casual readability. They can tidy up your code to a point where method or even class names are affected to form a block of code where you only have to replace the funnier chars with blanks to obtain a paragraph of plain written english anybody can read and understand.

What are your ideas towards Code Squiggles? Have you used them on your code? Mind to share the result?

Code squiggles are little methods that contain no functionality, other than directly returning the single given parameter. Their purpose is to make the code more fluently readable by casual readers.

14 thoughts on “Add flair to your code: Code Squiggles

  1. Pingback: Follow-up to our Dev Brunch June 2010 « Schneide Blog

  2. Pingback: geekinside's me2DAY

  3. Pingback: Fluent code – challenge your compiler « Schneide Blog

  4. Bizarre idea. I appreciate it improves readability somewhat, but when it comes to debugging other peoples code, how do you know that a squiggle is a squiggle without checking the contents of the method ? Repeatedly having to do that would hamper readability.

    Why not just replace your squiggles with /* whatever */ – it can’t have any side effect and barely adds any additional blocks to reading the intention of the code.

    • Hi None,

      I appreciate your comment and your proposal. Having comments in the code might be the passive alternative to squiggles.

      If you have to debug other people’s code, the last thing you should have to do is to look up all the squiggles and check if they are free of side-effects. That wouldn’t hamper readability (you can still read the code very fluently), but it would really degrade the accessibility (I hope it’s the right word, I’m not first-tongue with english). It’s not a big concern in our day-to-day work, but that’s just us.

      Thanks for sharing your opinion.

  5. Synchronicity: I found this article at more-or-less the same time that I found another article by Jeff Langr on the same thing (although he doesn’t call them code squiggles):

    http://langrsoft.com/jeff/2010/03/goofy-tdd-construct/

    I’ll ask the same question here that I asked at the linked article: How do you feel about code squiggles a year after having started to use them?

    • Hi Peter,
      thank you for the link and your question.
      We are still using code squiggles (or “active code comments”, as some might call them). They are valueable tools to increase the fluency of code readability, but nothing more. We often show this technique to other programmers and the usual first reaction is “uhh! What’s that for? This is distracting!”. If you have seen two or three code squiggles without being distracted or hurt by them, this usually settles.
      The value of code squiggles seem to diminish a bit in production code (as opposed to test code), because readability seems to be more of a concern with test code.

      To sum it up: I still think code squiggles are useful (once you get used to them) and we still use them. Their domain seems to be more in the test code, though.

      • Thanks for linking to my article. I’ve long been using the word “squiggles” to describe the curvy underlines that IDEs (e.g. Eclipse) put under errors/warnings, so I would prefer a different name than code squiggles. Pressed for a name, I suppose they’re simply echo methods. Kent Beck would probably call them Intention-Revealing Echo Methods.🙂

      • Hi Jeff,
        thank you for your comment. I really like the term “echo method”, as it is much straighter to the point than “code squiggle”. I will adjust my vocabulary🙂

  6. Pingback: How I met my coding style « Schneide Blog

  7. Pingback: An experiment about communication through tests « Schneide Blog

  8. For me, the most justified type of code squigless was using them for wrapping ugly array construction by using static methods with varagrs (and improve readability).
    i.e.
    static T[] strings(T … in){
    return in;
    }

    and using strings(“a”, “b”, “c”) instead of new String[]{“a”, “b”, “c”}

    Test code could became much more expressive this way.
    However, if used too much, the code would start to remind prolog fact declaration.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s