HOME    COMMUNITY    BLOGS & FORUMS    Future of Design
Future of Design
  • About

    My goal is to discuss advances in design methodology, particularly in the areas of low power design and raising the level of abstraction in design above the RTL level.

    - Mike Keating

Refactoring: Understanding Incomprehensible Code

Posted by mike keating on June 8th, 2009

Most of the code I read – and I read a lot of other people’s code – is utterly incomprensible at a first reading. In the last post, I described the major cause of this: the unstructured format of most RTL.

Chapter 3 of The Art of Good Design describes a project where I re-wrote (refactored) a large (28 page) module to make it simpler and easier to understand. The initial code was well-written and completely clear – to the engineer who created it. I was determined to understand its behavior without consulting the original author. Limiting myself to just reading the code, it took me weeks to figure out what the code really did. Even then, I had to restructure the code extensively to analyze it. My claim is that once I rewrote the code in a more structured fashion, the code became clear and obvious. I also claim that it is quantitatively much simpler – the state space is much, much smaller.

Here is Chapter 3.

Share and Enjoy:
  • del.icio.us
  • Digg
  • Facebook
  • Google Bookmarks
  • Print
  • Twitter
  • StumbleUpon

3 Responses to “Refactoring: Understanding Incomprehensible Code”

  1. You clearly demonstrate that refactoring improves the quality of your code. The only disadvantage of the technique is that you had to rewrite everything by hand. At Sigasi, we are working on automated HDL refactorings that save a lot of typing work. Because the tool takes care of all the syntactic and semantic subtleties of the hardware description, you will make a lot less mistakes.

    You could also add a section on how refactoring stimulates reuse. Through encapsulation, you can easily isolate functionality that can be reused elsewhere. E.g. the DMA FSM could now be reused in other designs.
    Since reuse is such a hot topic in (hardware) design, I would be interested to read your perspective on this.

  2. Jan Decaluwe says:

    Very interesting chapter.

    I didn’t like the perl stuff in the beginning. At least you could have used Python :-) This approach doesn’t feel right to me. As your input language is non-simulatable, the golden reference is not the input code, but the code that it generates. It should be the other way around. I prefer typing a little more to have it that way.

    However, I really like the rest for two reasons.

    First, the superiority of the single clocked process approach is clearly recognized.

    Second, another recommended guideline in the RMM is implicitly discarded. I’m talking about the guideline “not to mix blocking and non-blocking assignments in a clocked process”. The fact that you encapsulate blocking assignments in functions doesn’t fundamentally alter the conclusion.

    Still, I believe it would be useful to bury this guideline explicitly for the following reasons:

    1. Some functionality is really too trivial to warrant encapsulation in a function. There’s nothing wrong with a few blocking assignments embedded in a clocked process!
    2. Removing this guideline opens the way to the full use of “variable semantics” in RTL. Although only an minority of the designers understands it, this enables elegant coding solutions and is perfectly supported by synthesis tools. In particular, a variable can become a register, or a wire, *or both* after synthesis, depending on how it’s used. What matters is the behavior of the code – as it should be.

  3. Trackbacks/Pingbacks

    1. System-Level Design » Blog Archive » Blog Review: June 10 says:

      [...] are in Mike Keating’s blog about rewriting code to simplify it and make it more understandable. You’ll need to [...]

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>