Develop with Attention to Details

As a software developer or a tester a critical asset is the ability to pay attention to small details. Regardless of what kind of project you're doing everything boils down to a collection of details that form your product. Most people love to brag about these details when showing off their work. Details like how their game can render the most realistic bloom effects of any game with no impact on framerate. But individual details aren't the whole story.

Attention to detail doesn't just mean being aware of every little nit-picky speck of your brilliant piece of artistry. Attention to detail means understanding how each detail relates to each other detail. Your program isn't a list of discrete bullet points. Your program is all of the interactions that the entire set of points taken as a whole.

You may remember me criticizing the design of testlink's XML RPC API a few blogs ago. For this example I'm going to use testlink again. This time I'm going after the user experience of creating a test plan.

The process of creating a test plan within testlink is meant to be made up of a specific sequence of steps:

• Create any new test cases that are needed
• Create the platforms the tests are to run on
• Create the test plan
• Assign the platforms to be tested to the test plan
• Assign the test cases to be run to the test plan
• You're done!

So, pretty straightforward. Here's what happens behind the curtains (minus a lot of irrelevant details, mainly a ton of housekeeping work with the table nodes_hierarchy):

• Fill the database tables testcases, testsuites to create tree of test suites and cases
• Fill the database table platforms
• Fill the database table testplans
• Fill a join table associating platforms with testplans
• Fill a join table associating pairs of platforms and testcases with testplans

Still straightforward right? Except the UI of testlink doesn't require users to associate any platforms with a test plan before assigning test cases. This is reasonable since a lot of projects aren't multiplatform. Even if a project is multiplatform there's no obvious reason creating test cases first can't be done if mostly the same tests will run regardless of platform. Or at least based on the information presented by the UI.

This is what happens if test cases are associated first:

• Fill the database tables testcases and testsuites
• Fill the database table platforms
• Fill the database table testplans
• Fill a join table associating testcases with testplans
• Fill a join table associating platforms with testplans

The problem here lies in the fact that the 2nd to last step does not associate test cases in the test plan with platforms since that information isn't available. In most cases the final step doesn't correct the error causing testlink to enter a messed up state that a regular user can't easily correct.

Now, in testlink's defence, there is an attempt to detect the problem condition but it requires the user to notice an easily ignored "critic" message and follow instructions provided on it. The user has to first add a single platform to the test plan, save, then add the others. Assuming the user follows the instructions they'll have their existing test cases paired up with one platform. All of the other platforms added to the test plan need to have their test cases flagged manually. For most real-world applications this is highly tedious.

My first change is to automatically associate test cases with any platforms added to the test plan. My assumption is that if you're targeting multiple platforms you want the majority of your features to work the same on most platforms with a few exceptions. Adding those exceptions would be a lot less tedious than adding everything.

Now there's a problem with my approach which isn't a problem in the original. What happens if someone makes a test plan with no platforms, runs it, then decides to port their software to multiple platforms, showing this by adding all the supported platforms to their test plan in one go?

Feel free to comment with what you think the logic error in my fix (there is one) is. Hint: the instructions provided when testlink detects the problem (add one platform which associates with existing test cases, then all others) won't run into the logic error in my approach.

Comments on Test Driven Development

It's always nice to spend a bit of time on nerd rage. I was considering a follow up to my meta-rant instead of this but I'll refrain from doing so. If anyone wishes to have a follow up on something specific feel free to leave a comment. But before doing so, yes I'm aware of the author's weak follow up article. Stating (paraphrasing) "the article was a joke, rebutting it shows you have no humor" is, in my opinion, a cop out. Either back up your statements or admit you made mistakes. On to the actual blog.

Test Driven Development is Cool

For those who are unaware test driven development (TDD for short) is a method for making software where you start by developing automated tests for your program then write your program to pass those tests. It's a process which I'm a big fan of. Since I've been using TDD for a while now I figured I could share a few comments from my experiences using TDD.

Test Driven Development Makes you Think

More specifically, TDD forces you to think about how the code you're writing will be used. This is especially useful when designing an API. A typical process begins with you designing an interface for whatever you're doing, then writing tests that use that interface. Remember my earlier article on web services? For a short summary; I discussed how you should try automate common work within an API to minimize the code required to do useful stuff with it. I used Testlink's XML RPC API as an example of a suboptimal API. It's not awful but using it results in a lot of code bloat and, as a result, poor performance.

In order to develop a good unit test you need to first think of how your API is going to be used. Each potential use for your API becomes a single test. It's very easy to come up with a few dozen tests for a relatively simple API. Doing this you'll see what parts of the API get re-used very quickly, i.e. boilerplate. And if you're developing a lot of tests I think you'll begin to see why I refer to such code as menial bullshit. And when your API makes you angry you'll begin to think of ways of making it easier to use.

Testing is Faster with TDD

Let's imagine you're making a game. Games have a huge variety of data that needs to be stored. Sure, the absolute quantity of data isn't all that big (relatively speaking, financial and analytics software have games beat by lightyears) but there is a lot of very different data. Some things such as sound samples, music, 3D models, 2D images and such have established formats others such as game levels, entities, AI code, saved games, recorded gameplay footage (for games that still do that, I miss old FPS games...) tend to vary from game to game. And all of that data needs code to handle loading it into the game and saving it from creation tools.

Using a conventional dev/test cycle would mean creating the code, integrating it into the game and tools and finally creating content using the tools before being able to do any effective testing of the code. And testing the resulting data means opening up the game and tools and manually using them to see that the data is correct. In-game testing in particular tends to require going through a lot of extra effort (i.e. starting the game, getting to a testing level, and setting up your test.) That's slow.

Using Test Driven methods means deciding what sort of data your file format will initially contain producing some mock sample then writing unit tests that use your game's file loader to load the file then verify the data they produce matches with what you expect. Each unit test works with a small amount of data to verify a specific part of your file loader works correctly. You can also easily create additional tests to check that different combinations of features in your file loader work correctly. Obviously there's the risk of combinatorial explosion but that's easy enough to avoid by limiting unit tests to covering features in isolation and obvious feature combinations. This will give you the most bang for your buck. Other tests can be added if bugs are discovered.

The speed advantage comes from eliminated testing overhead. When you need to test your code you simply run your unit tests. No need to run your asset creation tools, or the game or anything else. The only limit to the speed of your testing is the speed of your code. The best part, if you're skeptical about TDD, is you don't need to fully buy into TDD to do this. Just supplement your manual testing effort with unit tests. Even better, if you automate your product's build process then you can have your tests run automatically too by making your build tool run the tests right after a successful build finishes. Your entire dev team can then be notified about failing tests just like they would be for build breaks.

Test Driven Development has Problems

So far I've painted an extremely rosy picture of TDD. However, like all processes, it's not perfect. Far from it in fact. There are a good number of caveats about using TDD.

You Must Make Testable Code

Remember my comment on testing being made faster by TDD? This is only true if your code can easily be unit tested.

This is both good and bad. On one hand testable code tends to be very easy to work with since it doesn't have a lot of baggage that prevents it from being picked up and used. On the other hand, that baggage may be necessary for your code to perform optimally. Nine times out of ten however you're best off developing testable code. And if you think you think your case might just be that one you're probably wrong. Check first. This applies to all code regardless of whether you're making web applications or embedded software on a high performance real time OS

One tip: modularize. This means not only conventional modularization by keeping objects and procedures from being overly inter-dependent, but also moving parts of your project into libraries to make it easier to build tests without pulling in huge quantities of code. This pushes compile times downward for when you're testing and allows faster testing.

You Still need Conventional Manual Tests

Unit tests and other automated tests that are commonly produced by test driven development are great for verifying software interfaces and behavior. However, unless you're producing automation tools, you're not going to find anywhere near the full set of issues.

For example, you can't test that your software's workflow fits your users' expectations. Automated tests can't verify that a game is fun. Artistic merit is impossible to judge with software alone. The most bizarre interoperability issues typically only crop up during general use of your software and require manual testing. For a completely contrived example on a smartphone, when playing music on a media player, visiting a flash site on one browser tab and visiting an HTML5 site on another and using the GPS causes the phone to crash at random. But only for certain commuters in the big city during rush hour.

Unless your test developers are completely evil and have a lot of time and money you're not going to get these kinds of things happening in your automated test. Particularly if you follow conventional best practices for unit tests which tests stuff in isolation. The only way you're going to find these issues is if you have manual testing reflective of how your real users would use your product.

Test driven development works as an excellent complement to ad hoc manual testing. Without TDD you're unlikely to have the tester time available to do the kinds of heavy exploratory testing that would find issues like our phone crash during a morning commute and without skilled testers doing that sort of testing you're unlikely to get the critical information need to fix the issue.

The Worst Anti-Java Rant Ever Written

Well, okay. I exaggerate, since this is the Internet there is always something worse. But I'm calling it the worst ever since I'm a jerk. Still; this is the dumbest anti-Java rant I have ever read. Frankly it's so bad it makes me question my position of being a Java hater myself. But then I think about AWT, Swing and GregorianCalendar and I get better

Since I've already made it clear than I'm a jerk I'm going to look at the guy's points and take them apart. Java, or at least Sun/Oracle's Java, is bad. There's no question about that. But if you're going to tear Java a new one try to find points that can't be validly taken apart or dismissed out of hand by a true-believer... or a hater that's pissed off at being potentially associated with such dreck. Without further ado, let's get this trainwreck a-rollin'

1) Java has a compiler

Ruby does not. That's great! Fuck compilers and their false sense of security. Too often is bad code checked in or even deployed to production, simply because it compiled. No such luxury in the Ruby world.

Seriously. That is your starting point. You know, most people tend to lead off with something big and obviously wrong with the language. How about the stereotypical FactoryPatternStrategyVisitorDesignPatternFactory classes that give haters so much ammo yet every Java-head is supposedly head-over-heals in love with. Or how generics suck in Java and took way too fucking long to get implemented. Or at least mention how compilers slow down your code-test-commit cycle by inserting an extra step. Fuck no, that would require something resembling deductive reasoning.

Oh, and believe me. I have seen more than my fair share of terrible Python, PHP, Ruby and Perl code in my few years of coding professionally. Not having a compiler does nothing to make a bozo's code magically better. All it means is that they'll produce shit code that is a nightmare to read that by sheer luck passes your unit tests. If they exist in the first place and if they even bothered running them. They certainly don't bother compiling before committing often enough! Guess what? Having a compiler vs not having a compiler will make no difference if the problem exists between keyboard and chair.

You shouldn't be making your code harder to check for stupid errors. Especially if it's to an attempt make fools less foolish. There lies madness. Remember the maxim "Nothing is foolproof to a sufficiently talented fool." A better solution is to keep fools away from your project or rely on the human element of training your fools to be less foolish. Nothing is stopping you from having a quarantine branch in your project; Or having a list of restricted contributers.

Oh! Just for a bit of icing on the cake. Ruby can be compiled and often is (except in the default Ruby implementation.) Why can it be compiled? For the main reason compilers existed in the first fucking place. To convert human readable, but sub-optimal code into high-performance machine readable code. And what is one of the most popular things to compile ruby to? Fucking. Java. Bytecode.

2) Java framework authors are not application developers

Prime example: the JBoss guys, who are paid handsomely to work on framework code all day. Sure, they're exposed to real application development, but they don't do it themselves. As a result, none of their handiwork is extracted from actual working codebases. Which is a shame, because if it were extracted from actual working codebases then it might actually not suck. All Rails core and plugin contributors of significance are fulltime application developers, starting at the top with DHH himself and the Rails core team. Day in and day out we write applications in Ruby and extract the useful bits out for other Rails developers to make use of via gems and plugins.

This is about the closest our wonderful author gets to a potentially valid point. I can't make any comments on JBoss since I avoid Java like the plague but given this guy's track record I'm disinclined to give him the benefit of the doubt. But since I relish the opportunity to bash Java: let's look at WORA, a pillar of Java's language philosophy. Sounds wonderful on paper. Collapses like a house of cards as soon as you try to apply it to real hardware. Joel on Software can explain the cause. (article not related to WORA directly but I'm assuming you're smart enough to see the connection!)

Contrived example time! Let's go back in time to the heady days of the mid-late nineties when Java was all the rage. Let's imagine we're making a wonderful new GUI application with Java. So you get it working on your awesome top-of-the-line dev machine. Now it's time to test... and your user tells you that it dies. Why? Your user heard of this awesome thing called J2ME, Java on a cellphone. It's Java and Java is WORA so it should work. Right? Guess what, a shitty nineties era cellphone isn't going to handle a GUI application that is made for desktop.

Okay that's extreme to the point of silliness but the philosophy is Write Once Run Anywhere not Write Once Per Platform /trollface. Let's go with a more likely case. You're using some nice portable library but not every feature you're using in some library is supported on your users' hardware like it is on yours. Obviously you want to take advantage of the features when available. So what now? Hello special cases and hello code bloat. Or the alternative you're using the lowest common denominator in your code so your lunch is being eaten on high end hardware by people who didn't drink the WORA koolaid. Then your product dies because high end systems become low end systems within a year or less. But I digress. I'm here to bash someone else's anti-Java rant. Not write my own.

3) Most Java Programmers are Morons

And there goes any possible validity point 2 might have had. Oops.

So how does this detract from point 2? Well, let's imagine a world where most people are stupid. One solution is to have an omniscient council of vagueness dictate the process which uses the framework built from the lofty heights of their ivory tower. Obviously the whole thing fails horribly on encountering the nuances of real work. Exactly what point 2 says. So instead we have the masses build a framework of useful tools based on practical lessons learned in the trenches. Well look what point 3 says. The masses are idiots. So that won't work either. You just end up with a mess of unusable broken garbage. At least according to our buddy's assertions. So let's get the smart people together to make a framework from their ivory tower...

The obvious rebuttal is that the circular logic above actually bolsters point 2. Guess what, if you go that way you've got Argumentum ad Hominem It's the classic "You're stupid therefore your argument is false." Don't try that rebuttal. This whole point is also an argument by assertion Yes, most Java programmers are stupid. Guess what most programmers are stupid full stop. In fact most people are stupid.

That especially includes the author of this tripe for making the wonderful non-argument I've spent the last two paragraphs deconstructing.

Oh, and I spared you the meat of his argument since it amounts to "all the cool programmers are using stuff that isn't Java therefore Java programmers are stupid." I'll be attacking that one further down since it rapidly becomes a theme in our buddy's later points... And you wonder why I'm insulted this idiot is a representative of Java haters online.

4) Java is too Fragmented

Java has a gazillion open-source frameworks and they all suck ass. So what do Java teams do to cope? Cobble those suck-ass frameworks together into custom layered homebrews that are nothing more than exponential explosions of sheer, despicable suck-assiness.

In stark contrast, in the Ruby world, we only have Rails. All Rails projects are structured the same way and follow the same conventions. That's a good thing, since it means that Rails developers can move across projects with relative ease.

And the Rails fanboy reveals himself. What if I don't want to make a web application clever writer? What then? What the holy fuck then asshole? Java does have a lot of frameworks. Guess what? All open source languages have piles upon piles of frameworks, tools and random shit out there produced by the community. Good ones, like Rails, will be picked up by the community and become de facto standards. Let's see, how many authentication methods exist for Rails again? RESTful Authentication, AuthLogic, mod_auth_sspi, OpenID authentication and on and on. Fragmentation is a fact of life for Open Source. Don't like it? Join the thousands of developers working with Microsoft and Apple's tools instead. You might like it.

Oh, and let's not forget. Almost every single open source framework out there exists because some developer got annoyed with existing frameworks and made their own letting their experience guide them. Your precious Rails is yet another framework in the great morass that is the world of open source web application development frameworks. DHH saw a problem, wasn't happy with existing solutions, and made his own. And it's a damn good solution but he isn't exactly a dictator forcing the Ruby and Rails communities into the One True Methodology. The community embraced Rails of its own collective volition. It wasn't forced to do so.

5) Java is Too Slow

Ha. This is one of my favorite reasons, for the bloody irony of it. You see, Java isn't actually slow. Everyone reading this knows that it got plenty fast over the last five years or so. Nevertheless, 90% of the world that knows of Java thinks that it is slow, because of its association with crappy slow Java applets and crappy slow Java loading screens on mobile devices.

Ruby *is* slow, compared to Java, and yet it is fast enough. Amazing, isn't it.

Let's translate. "People think Java is slow even though it isn't; at least for well designed applications. So let's avoid using it because people will be prejudiced against applications listed as using Java." Guess what? You don't have to shove it in people's faces that you're using Java. Next!

6) Java doesn't have blocks and closures

It's a miracle. We finally have something that isn't a bare assertion and is a valid point. Functions as first class objects, anonymous functions and closures are extremely powerful tools for building useful algorithms with a minimal amount of code. Java isn't as expressive as alternatives such as C#, Ruby, Lisp and Python. This can lead to the stereotypical bloat of the pathologically bad Java application. However being less expressive than other languages doesn't automatically make a language bad. C for example is as good as it ever was for its purpose.

This is the kind of point you should tack on after all your hard-hitting points. The blub programmer isn't going to care about things they haven't experienced like closures. What they would care about are actual annoyances like how AWT/Swing applications are ugly crap in comparison to Qt, native or web-based alternatives. Or how the built in date/time libraries are a pain in the ass to use. In fact that's an ongoing theme of this essay so far. It's bare assertions followed by smug self-satisfaction at not using Java.

7) Java has Integrated Development Environments (IDEs)

Closely related to Reason #3 Most Java Programmers are morons. Everyone knows that the best programmers use Vim and Emacs. Then come the TextMate users. If you need to use an IDE then you suck, period.

I sincerely hope this point is a joke. This is something that massively pisses me off about certain Open Source advocates. Because tools might make life easier for a moron and lower the barrier to entry for programming newbs everyone must use the worst, most obsolete, tools possible. Not everyone does this. Our author's precious DHH (all disrespect aimed at the blog author, not DHH, nothing but mad props for him :) wasn't satisfied with the tools that existed and made something that makes web development easy and fun. I don't see the author bashing Rails despite the fact it makes development easier just like any other good tool.

No, a good developer doesn't need tools to make their life easier. But a good developer is also a lazy, easily annoyed, impatient, stubborn asshole. Guess what? I'd rather be solving interesting problems with my programs than dealing with breaks due to typos and other silly mistakes. An IDE with autocomplete and syntax checking built in lets me avoid that menial bullshit and move on with my life. Let's throw in a line debugger with watches and stack monitoring, code folding for faster reading, and shortcuts for kicking off your build tools, unit tests, program binaries etc. all accessible within your text editor and you've pretty much got an IDE.

How about another comparison? Would you say I Wanna Be The Guy is a better game than Super Mario Bros 3? It's certainly a harder game. But it crashes, the artwork is crappy and about half the deaths are bullshit surprise deaths that are unavoidable until you memorize the game. And it fucking crashes. Last I checked the consensus is that SMB3 is the main contender for best platformer evar and IWBTG is something that's for laughing at hapless Let's Players. Confession: I love playing through I Wanna Be The Guy. The game is a parody of the bullshit difficulty of many NES era games and modern romhacks. And it is glorious. Without the parody context it's not so great however. YMMV

8) Java has good debugging support

Java has great and powerful debugging (which is very necessary since most Java code sucks so much ass). Ruby has ridiculously pitiful debugging support, which means our code actually needs to be well-tested and readable.

See above. Unit tests, system tests, integration tests, static analysis *cough*includingcompilers*cough* and every other non-debugger tool under the fucking sun won't catch everything. You will have bugs. It's nice to have a useful tool for finding those obscure corner cases that the tests didn't catch. I have more important things to do with my time than tediously inserting trace code into my programs in some vain attempt to emulate what a proper debugger provides out of the fucking box. Next.

9) Java Makes a Lot of Money for Vendors

This is potentially the most subtle of all of the reasons on the list. Basically, the integrity of most anything having to do with Java is corrupted by the way that it is inextricably linked to a web of intrigue involving money, big vendors and bullshit enterprise politics and pandering. Ruby doesn't make major money for anyone except Pragmatic Dave.

Hoo boy; it's another random assertion pretending to be an argument.

This reminds me of an anti-Rails rant I read today. It's more interesting due to DHH's rebuttal than its own content but a relevant point went like this: something something shitty documentation something something selling books something.

Anything that gains popularity will make money for someone. Often many someones. Books, consulting, evangelizing, training and, of course, the resulting products all inject money into a language's or framework's ecosystem. I'm pretty sure O'Reilly, Twitter, Hulu, Yellow Pages, 37signals et al didn't use (or create, or write about) Rails for the purpose of losing money. Either way, anyone who has a stake in a particular framework, regardless of the reason, will want to influence it.

Peoples' desire to influence other people will mean politics. Last I checked most open source frameworks have some level of politics and politicking to deal with. Politics that relates to programmers' egos and personal beliefs in The Right Thing. Look at the flamewar over Javascript's implicit semicolons. And how many forks of various major projects were made specifically because someone didn't like some particular nuance? Funpidgin ring any bells? Last I checked none of the people involved were faceless corporate entities. Just stubborn egotistical asshole programmers. Hell, look at the most infamous anti-rails rant on the Internet. Most of the anger is directed specifically at the politics of the community. This sort of shit happens. Especially in open source. Get over it.

10) Java does not have DHH

In the words of my inimitable friend Zed Shaw, "If DHH ain't doing it, you don't fucking do it. (Seems every time some clever fellow gets into trouble it's because of that.)"

Who does Java have? Jimmy Gosling? Hahahahahahahaha...

Sigh. You just had to go there. You just had to go with the "my visionary is cooler than your visionary" argument. You just had to go with the most childish, insolent, smug, short-sighted, juvenile, peabrained, puerile, putrid, pointless, pissy, motherfucking worthless shitstain of an argument possible. Do you hear people advocating Python solely on the basis that it has Guido van Rossum (aka BDFL) at the helm? Not too often. People advocate it because of his vision, stupid. Why don't you speak of what DHH contributes to the community? How he is actually able to create a useful tool and eloquently defend his decisions for Rails against complaints. Like he does here. That is how you get people behind you. That is how you make sure everything created in your ecosystem closely follows your vision.

But noooooo. You just had to resort to the fucking mocking. Your point is presented stupidly. How about this? How about you try attacking Sun or Jimmy Gosling for specific missteps in how they've managed their community and caused Java to suffer versus how DHH succeeded? Maybe then I wouldn't have to call you a fucking douche. You fucking douche!

Closing Words

Well. Fuck. That was exhausting. And writing this bitchfest took a bit of effort too.

I appreciate the sentiment of the article in discouraging the use of Java. The sooner Java dies, the better. The poor quality of the article I've ranted about does nothing to diminish the shortcomings of Java or the superiority of any alternatives. I wish the article did more to highlight hard facts about what makes Java bad instead of sucking up to DHH and poorly advocating Rails.

In the words of Jon Stewart

Making of an Arcade Frontend - Part 4

Previous entries:
Prologue
Part 1
Part 2
Part 3

Last part I talked about some boring math used to create a pretty rotating list of games. This time I'll be showing some more code. The goal today will be to have a smooth transition between game titles on the list.

So, here's what we're starting with. The code to position and draw the rotating games menu. No special effects and no transitions, the selected game is in the middle. Don't forget to read the comments since they cover most of the "clever" parts of the function.

# NOTE: These functions are members of a class.
# I've omitted most of it since it's not relevant to the example


def _selectorPos( self, i ):
    # Here's the math that was discussed in the previous blog!
    x = self.radius * math.sin( float( i ) * 3.14159 / float( len( self.selectors ) - 1 ) )
    y = (i - self.selectedIndex) * self.spacing
    return (x, y)

def Draw( self, screen ):
    # Draw the top half of the menu
    for i in range( self.selectedIndex ):
        pos = add(self.center, self._selectorPos( i ))
        # Rect is a tuple of vectors
        # The first is the top left, the second is the bottom right
        rect = (add(self.pos, neg(self.unselectedSize)), add(self.pos, self.unselectedSize))
        self.selectors[i].Draw( screen, rect )

    # Draw the bottom half of the menu
    # Reverse order so items closer to the center are drawn on top of ones further away
    for i in range( len( self.selectors ) - 1, self.selectedIndex, -1 ):
        pos = add(self.center, self._selectorPos( i ))
        rect = (add(self.pos, neg(self.unselectedSize)), add(self.pos, self.unselectedSize))
        self.selectors[i].Draw( screen, rect )

    # Draw the currently selected item, last so it's on top
    pos = add(self.center, self._selectorPos( selectedIndex ))
    rect = (add(pos, neg(selectedSize)), add(pos, selectedSize))
    self.selectors[selectedIndex].Draw( screen, rect )

Notice I've hidden some math away in functions. This makes the purpose of this code easier to discern since it's not buried in a ton of repetitive arithmetic. The functions add and neg are 2D vector addition and negation. Since Python provides tuples as a built in type I used them to represent vectors. This can be bad for performance because every time I do math on vectors a new vector gets created. That means lots of garbage objects for the garbage collector to clean up. Optimization is as easy as replacing tuples with a mutable type and would have no effect on this code since all the real work is hidden in functions. I haven't done so here because it hasn't been an issue.

So if we use this code to display a menu it will display a list of games in a nice circle with the selected game in the middle at one size, and everything else above and below it at a different size. Items further from the center are displayed behind ones closer. This allows items to overlap if I want and still look reasonably good.

Now, if you remember the skeleton I showed in Part 2, I had some code for responding to input. Now it's time to update it to allow the selected game to change. New stuff is in italics

# the main loop!
frameStart = time.clock()
time.sleep( 0.01 ) # XXX: don't want a frame time of 0 when starting
while True:
    frameTime = time.clock() - frameStart
    frameStart = time.clock()
        
    for event in pygame.event.get():
        if event.type == pygame.QUIT or (event.type == KEYDOWN and event.key == pygame.K_F12):
            sys.exit()
        elif event.type == KEYDOWN:
            if not selector.InTransition():
                if event.key == pygame.K_DOWN:
                    selector.Next()
                elif event.key == pygame.K_UP:
                    selector.Previous()
        
    selector.Update(frameTime)
    selector.Draw(screen)
    pygame.display.flip()
    screen.fill( (0,0,0) )

Nothing too surprising I hope! The only really special code here is right after the new KEYDOWN check. The checks simply make sure the person using the launcher can't change the selected game while the selection is in the process of changing. The code for selector.Next and selector.Previous is about the same. It sets a flag in the selector object to make it change selections. The work of changing selections happens in Update and Draw. Update maintains a timer which lasts for about 1/5th of a second. It also stops the timer and changes the selected game once the timer expires. Draw handles positioning everything based on the value of the timer. If no transition is happening the drawing code I showed you at the top is run. Otherwise some different code runs...

alpha = self.timer / self.transitionTime

# Draw the top half of the menu
for i in range( self.selectedIndex ):
    pos = add(self.centre, blend(self._selectorPos( i ), self._selectorPos( i - 1 ), alpha))
    rect = (add(pos, neg(self.unselectedSize)), add(pos, self.unselectedSize))
    self.selectors[i].Draw( screen, rect )

# Draw the bottom half of the menu
for i in range( len( self.selectors ) - 1, self.selectedIndex - 1, -1 ):
    pos = add(self.centre, blend(self._selectorPos( i ), self._selectorPos( i - 1 ), alpha))
    rect = (add(pos, neg(self.unselectedSize)), add(pos, self.unselectedSize))
    self.selectors[i].Draw( screen, rect )

# Draw the old selection
pos = add(self.centre, blend(self._selectorPos( self.selectedIndex ), self._selectorPos( self.selectedIndex - 1 ), alpha))
rect = (add(pos, neg(blend(self.selectedSize, self.unselectedSize, alpha))), add(pos, blend(self.selectedSize, self.unselectedSize, alpha)))
self.selectors[self.selectedIndex].Draw( screen, rect )

# Draw the new selection
pos = add(self.centre, blend(self._selectorPos( self.selectedIndex + 1 ), self._selectorPos( self.selectedIndex ), alpha))
rect = (add(pos, neg(blend(self.unselectedSize, self.selectedSize, alpha))), add(pos, blend(self.unselectedSize, self.selectedSize, alpha)))
self.selectors[self.selectedIndex + 1].Draw( screen, rect )

There's quite a bit of new stuff here. There are a bunch of calls to a new function "blend." What it does is create a new position that's "alpha" percent between two positions. 0% is at the first position, 100% is at the second position, 50% is right between the two. There are three variations on how blend is used.

blend(self._selectorPos( i ), self._selectorPos( i - 1 ), alpha)

This makes the items rotate upward. The top item goes offscreen and disappears, the item below the selection becomes the selected item and a new item slides onscreen from the bottom.

blend(self.selectedSize, self.unselectedSize, alpha)
blend(self.unselectedSize, self.selectedSize, alpha)

These make the old selection go from the size it has when selected to the size of everything else and the new selection go to its selected size.

A Mini-rant on Documentation

If you're releasing a non-trivial API... for example a YAML parser for .NET. Please remember to document the most commonly used functions so it's easy to understand how they relate. Whatever you do, don't write undocumentation.

What is undocumentation? Well, if you didn't follow the link, it's something that looks like documentation but is devoid of anything that makes it useful documentation. Like this:

// Default constructor for the Node object
Node::Node()
{
   // do stuff
}

This documentation says nothing that the code doesn't already say. Writing documentation sucks. I know. But in this case not writing documentation is an equally meaningful alternative. And it saves everyone time. Particularly me since I now know I have to search for code samples or troll message boards and Stack Overflow to get the information I want.

Rant over.

If you insist on taking the time writing documentation make sure whatever you write isn't stuff made obvious in your method signatures. To mangle DC Comics for a second; a constructor is. You don't need to tell me it's a constructor. Tell me what isn't shown in the code. Tell me when I might use it. Tell me how I can cause it to fail. Tell me why I'd need it in the first place. Every piece of your documentation should provide a hint about how you intend your functions to work together. Preferably, these hints should be about as subtle as a pile driver.

Ruby on Rails and the Standard Python Library are both generally good examples of documentation. The parts of Ruby itself that I have used were also generally well documented. For all its faults the parts of the Java library I have used were well documented. The issue there was more the godawful design of what I had to work with.

Programmers are lazy and have a low tolerance for unnecessary work. You know best how your API should be used. You should let your users know what you know. A nice side-effect is, usually, more, and happier, users.

As an aside. The YAML parser I mentioned above otherwise looks good. I might make another, less harsh, post about it earlier. I want to use it. But it's taking longer to grok than I'd like. The result was this rant.

A Look at Web Service API Design

Lately I've been spending some time working with the open source test tracking tool testlink For tracking manual testing efforts and linking tests to software requirements and other SDLC essentials it is a very nice tool. However its API leaves something to be desired. So today's topic is designing a usable API.

The purpose of the API is to allow automated testing to be tracked and reported in testlink much like manual tests are. In addition it could be used to provide a hook into an automated build system so testers are aware of new work asap. Testlink tracks test sets in two ways. First is test suites. These represent your entire pool of available tests. Second is test plans. Test plans represent some set of tests you need executed by your testers or your automation system and are taken from the test suites. Test plans are executed against builds of your software on one or more platforms (eg windows and Mac)

So with that background we can come up with some ideas for what we need in an API and compare with what testlink actually provides. Let's assume that you already have a working automated build and test system but need better reporting because there is too much data to work with without a tool to help. Since this system is already running and more or less fully automated it's pretty unlikely that anyone would be willing to manually add anything major to the database such as test case information and such.

Given that... Here's what I would expect a reasonable API to provide.

• Create a test case within a suite which may be part of another suite. Also create the suites if they don't exist.
• Create a test plan containing a list of pre-created test cases. Update as appropriate.
• Assign results to tests in a test plan run against a build for a platform.
• Create a build and associate it with a test plan (or several)

Not too much eh? The nice thing is that this hides a great deal of complexity which is handled manually in normal testing. Hiding complexity is always a major goal for a good API. Another advantage is that this concept keeps requests larger and less frequent. When dealing with distributed systems you pay a fixed time cost for every request made. That cost goes into negotiating connections, security, protocol headers and so on. So, fewer requests to a web API is usually faster.

Sadly testlink makes a very easy mistake in its API design. The developer chose to expose every simple step used in creating test plans and recording results except for a few cases where the API is more difficult to use than necessary. The list of actions look something like this

• Create a single test suite optionally belonging to another (bad stuff happens if the suite already exists)
• Create a test case belonging to a previously created test suite (ditto)
• Create a test plan
• Create a build
• Create a platform
• Assign a platform to a test plan
• Assign a test case to a test plan
• Record a result for a test case in a test plan run against a build for a platform
• Yadda Yadda blah blah.

So. A user of this API needs to jump through the same hoops as they would when doing things manually. While this saves mental effort in designing the API you end up paying for it every time you have to write code to check that a suite (and the suites it's contained in) exists and create everything that's missing via a dozen or so function calls. Not fun.

Think of an API as a time investment. The more menial bullshit your API does for you the less you have to do when using it.

One last example. A test case in testlink has a number of properties such as its author, a description and the steps that are taken to carry out the test. When you use the testlink API you provide a key (a bunch of gibbrish) to get access. The key is unique to you. Now when calling an API to create a test case using your key the API ought to be smart enough to assume you are the author unless told otherwise. The version of testlink I'm using fails to make this leap. This means you need to modify the API (I did this, small win for Open Source) or have both a user name and their key to use the API for just this one function. Again if an API can reasonably do something for a user it should.

Making of an Arcade Frontend - Part 3

Last part of this series I talked about how I started coding up the arcade frontend based on translating the features I wanted into tasks the program has to do. One thing I want to do when starting any project is work on tasks that provide the most benefit for the least effort. The strategy I used in the previous part was to pick a task that was needed for a lot of features to work (finding information on games to launch.) The final result is a nice skeleton which I can build the launcher around.

Today I'm going to talk about a second method of getting a lot of visible bang for your programming buck. That is by finishing tasks for the most visible features in the program. In short, make the user interface before other stuff. The first method (finding common tasks and doing them first) is roughly the same as bottom up development for those into jargon. This method of building programs is normally known as top-down development.

If you don't get the names try to imagine a program being like a cake. Top-down means starting with the icing and decorations while bottom-up means starting with... well... with the bottom. Both methods have their gotchas. building from the bottom up tends to mean you have something unappetizing until you're all done your work. But, building from the top down means you have a hollow shell made of icing and fondant. It looks complete and appetizing but its missing everything that makes it a cake.

With that in mind I prefer to do both at once. This way of doing things doesn't translate very well into my cake analogy. The closest idea is to build a cake one slice at a time. What you get is kinda tasty, but obviously incomplete. You end up with something that can be released very quickly that gradually improves until you're done.

Anyway; enough about cake. Let's talk about the arcade frontend... I'm going to create a graphical menu to pick out a game to start. I drew inspiration mainly from the rotating song menu in Dance Dance Revolution. Playable games will show in a semicircle with the selected game in the middle at a larger size than the others. selecting a new game rotates the menu and you can rotate forever in either direction.

To get the right look requires a bit of math. placing the titles vertically is simple... sort of. Dividing the screen's height by the number of visible items will give you the amount of space each item can take. If you take that number and halve it you get the distance to the center of each space that can be used.

Now, I'm guessing a few people are asking why I need the center of the space where each item goes at all since PyGame draws images positioned at their top left. The reason is that the center of each item will stay the same no matter how large or small the item gets. It's very easy to calculate the top left of the image by subtracting half of the image's size from its center. It's not so easy to calculate the top left of the image relative to the top left of the  The image below shows this better than words can.

Another thing to note is that I'm using an odd number of games in the visible part of the menu. This way there's one "middle" game which is the selected game and an even number of other games around it. Having an even number of games would result in the selected game being off center which looks ugly.

Placing the titles horizontally requires a bit more math knowhow but not much. If you remember your trig class you might recall that the sine function looks like a smooth set of waves like this.

Source: http://images.yourdictionary.com/sine-curve

In programming the sine function usually uses a unit called radians. Radians are how mathheads measure angles. You can do some cool tricks with them once you get it. The important part is that half a circle (180 degrees) is equal to Pi (3.14159...) radians. The cool part is that sine between 0 and Pi radians looks exactly like half a circle. In fact the value of sine at any angle matches how far you are from the center of a circle vertically at that angle.

With that all that needs to be done is to multiply the item number by Pi then divide it by the number of items that are to be visible plus two, put that number into a sine function, then multiply the result by the radius of the circle. Why plus two? In order to support spinning between games an extra game is to appear offscreen and slide onto the screen when changing selection. If we don't take these two items into account games coming onscreen from the top or bottom will wobble to the left or right.

Here's the result of all that math

Not too bad eh?

Next entry I'll be showing some code and talking about how to handle transitions between titles. I'll also show you the code that this entry produced as well.