Tag Archives: best practices

NorDev 1

โ€œIt’ll be all right on the night!

And it was! OK, so we had one helper and an organiser drop out at the last minute due to illness; my dinner was a bit rushed; I forgot the memory cards for my camera; I forgot to return the memory card I attempted to borrow; I rather fluffed the wonderfully witty and insightful intro talk I was going to do (twice, given we split it into two chunks); and the projector was playing silly buggers… but I don’t think anyone noticed (well, maybe they noticed the projector, but we’re techies, we expect this kind of thing).

NorDev 1 is in the can and Norfolk Developers is on the map. Our opening night saw nearly 50 developers descend on Virgin Wines in Whitefriars to see Liz Keogh and Phil Trelford talk, as well as enjoy a glass of fizz and a brownie or two.

Liz was, as always, fun and engaging as she detailed the differences between lean and agile practices in a 6 round “fight” with a wicked twist at the end. Given most of my team attended the talk I suspect we’ll be adopting much of what was talked about and becoming more lean over the coming weeks and months – actually, even if they hadn’t attended I’d probably be foisting a lot of it on them, but it’s nice to get buy in from the start, and for them to understand why ๐Ÿ˜€

Phil’s talk was funny and hugely interesting, even for a Java developer like myself. Having a room full of devs meant he could fire up the IDE and write code live during the talk, something that is helpful when faced with a new language. I find myself hankering after something F#esque for the JVM.

Despite the hiccups I think everyone had fun, people found it interesting and, hopefully, will come to NorDev 2 (Wednesday 10th July… which only seems to be 2 weeks away, eeep!). No doubt it’ll bring its own set of hiccups ๐Ÿ™‚

Side Projects

A number of years ago I was interviewing someone for a position as a senior software developer at a market leading financial institution. This was a job with a large pay packet, excellent benefits package and potential for reasonable bonuses, so we were being understandably picky. One of my [fairly standard, even now] questions was to ask what development activities he did outside of work. His response was that he spent all day working with computers and that he didn’t want anything to do with them during his free time. The interview was effectively over from that point on.

Software development, like most other technology disciplines, moves at a rapid pace. If you’re standing still you’re moving backwards and it’s frightening how fast you can become obsolete. While you can learn on the job it does require the job containing useful elements you can learn from, and the chances are what you work on day to day isn’t going to be bleeding edge.

The easiest way to reconcile this is with side projects; something worked on during your spare time that allows you to investigate new technology, new languages and new ways of doing things. Interestingly though, I generally find those developers who have side projects are not doing them due to a professional need to keep up, it’s from a personal need to learn. They’d be playing with this stuff even if they didn’t have to.

For me it’s this hunger to learn that makes a good developer. Experience helps, but you can gain experience, I’m not sure you can learn the hunger. It’s not just me who thinks this either, an increasing number of top name technology firms allow their developers to spend a certain portion of their work time on side projects. Even if the project itself end up providing no benefit to the company, the experience, lessons learned and morale boost this practice provides can only help the developer become better and more productive.

There is another side to this though. Developers can be fickle creatures and they can get bored easily. When this happens productivity crashes, and more than likely they’ll start looking for a new job. The day job is never going to be as interesting as the side projects buy its very nature – the product has to make money, and has to satisfy more criteria than simply “be fun“. By accepting that your top guys are going to have side projects, buy allowing them to find what interests them and spend a little bit of time during work time, you’ll find they keep themselves interested.

The question shouldn’t be “why is this developer spending a long lunch working on something not work related?“, the question should be “why aren’t all our developers doing this?“.

Logging

A personal bugbear of mine is developers not being able to write clear, effective logging. This seemingly trivial task appears to cause a great number of developers no end of problems, and yet it shouldn’t necessarily be that hard. Why is it then, that when I go to interrogate a log file I have to trawl though kilobytes (or worse) of meaningless rubbish to determine that:

24/04/2013 09:26:19 [ERROR] [Batch941-Thread5]: Unhandled exception has occurred null

That’s a real error message from a system I work on, and that’s all it had to say about the matter. I despair.

There’s a few basic things you can consider that will make you logging a lot more effective.

Use the appropriate log level

Fatal should be reserved for when an application, or a thread, is about to be terminated in a fashion that really isn’t expected. Errors should indicate something recoverable [at an application level] that’s gone wrong that wasn’t expected. The vast majority of fatal and error log messages are really warnings, that is messages indicating that an error has occurred but we’ve been able to carry on. Any occurrences of a fatal or error level message in your logs should have attendant bug reports with either code or configuration fixes to remove those errors. Informational messages should relate to things that people will care about day-to-day, or as additional log output for an initial higher level log output. Everything else is a debug message and will generally be turned off in production systems.

Provide the right level of information

Logs are text, are often large (I’m looking at 2 production log files that are in excess of 12Mb) and are often going to be parsed with simple tools. If I use grep ERROR *.log I should be able to see each error, and enough information about that error to give me a high level overview of what is happening. More diagnostic information can follow the initial error at lower logging levels. There should be enough information following the error that someone reading the log file with default production settings can diagnose the issue, but not so much that they’re drowning in log lines.

Format the messages correctly

Be mindful that when you concatenate strings you may need spaces and other delimiters between output. When you split your output over multiple lines those lines may not be seen on an initial parse of the file. Also, be mindful of how values are going to be displayed. With Java the default toString method on an object isn’t the most useful of outputs in a log file. In contrast, some objects are verbose in the extreme and may break the formatting of your error message by spewing a multiline string onto your single line error message.

Some real world examples

I regularly check our production log files for a number of reasons and find myself facing such doozies as:

30/04/2013 08:45:41 [ERROR] [[ACTIVE] ExecuteThread: '2' for queue: 'weblogic.kernel.Default (self-tuning)']: Error

The kicker here is that this could be one of a number of errors. If I see this twice in a log file I have no way of knowing if it’s the same error twice, or two different errors. The error message is badly formatted with the information [hundreds of lines of it] on the next line. Sadly I see this more than a couple of times a day and, as it’s a third party bit of code that’s responsible, theres’ not much I can do about it.

30/04/2013 15:29:28 [INFO ] [[ACTIVE] ExecuteThread: '7' for queue: 'weblogic.kernel.Default (self-tuning)']: Email transport connection established
30/04/2013 15:29:29 [INFO ] [[ACTIVE] ExecuteThread: '7' for queue: 'weblogic.kernel.Default (self-tuning)']: Email transport connection closed

126 occurrences in todays log files. This needs to be a debug message and an error output if it fails to establish or close the email transport connection. Ironically enough, as I was digging into the code to fix this I discovered that when it does go wrong it reports the error 3 times in 3 different places, resulting in 3 error lines in the logs. Worse still 2 of these lines only state “Error sending email” with no other information other than a stack trace from the exception. That’s three slightly different stack traces, two useless error lines and one useful error line for 1 error which could easily add 15 minutes to the diagnosis time while the developer tries to work out what’s going on.

01:17:45 [ERROR] [[ACTIVE] ExecuteThread: '7' for queue: 'weblogic.kernel.Default (self-tuning)']: Failed to create URI Object

Well over 1000 occurrences today alone! My grepfu is reasonable so it I altered it to show the line after that. Turns that someone is trying something nasty with some of our search URLs, but that wasn’t immediately obvious from the error, instead I was resorting to the stack trace. Not only could the error be improved, but we can also downgrade this to a warning. Looking at the code this is only going to happen in two cases: either someone has put a bug in the code, in which case we’ll see thousands of identical warnings and do something about it; someone is trying something nasty when we’d see hundreds of variations on the warning which we can investigate and then improve or ignore depending on the outcome of the investigation. Bug raised to fix both the handling of dodgy URLs and the logging level.

I’m sure I could dig out loads more and thats just with a cursory glance of the files. Logging is an important diagnostic tool, but it’s only as good as you make it.

Revisiting Git

I first discovered Vincent Driessen’s branching modelย when I was investigating Git a couple of years ago. At the time I was desperate to get away from the merge issues that we were having with Subversion and was looking into both Git, and different branching models using it. Given the steep learning curve with Git we decided not to complicate things further and to stick with our old branching model; albeit with a slight change in naming convention borrowed from Vincent.

Now I’m a little more comfortable with Git it’s time to revisit our branching strategy, and use of Git overall. I’ve looked at Vincent’s branching model again, and looked at git-flow in great depth and have concluded it’s still not for us, however, the idea of codifying the workflow, and providing git extensions to aid using the workflow appealed to me immensely.

Currently we’re doing little more than branching off master for issues, with each issue (be it a new feature, or bug fix) living in its own branch. Issues are rebased into master when they’re done. Releases are also cut from master and any patches (either to the release version in QA, or to the release version in live) are cut from the release branch, rebased into that and then rebased into master.

In order to simplify our JIRA and Fisheye/Crucible setup we also push issue branches to origin making them visible from a central point, as well as providing a backup. These branches are considered private and not used by others.

Since we have tight control over all the branches a rebase only strategy works fine for our team, although we have had some problems caused by accidental merges. The next step is to improve the workflow and the merge/rebase strategies to survive all situations, codify these steps and then script them – something I’ve already started doing.

I’m also looking at this as a potential opportunity to possibly move away from Fisheye and Crucible to Stash, potentially saving some money whilst keeping the tight JIRA integration.

Tumbler and low level stories

I’ve run into a bit of a brick wall with Tumbler in so far as I think I’m using it at far too low a level. I’ve got a fairly simple object at the moment, little more than a bean, which I’m using as a working example to try these new techniques out. While my first story and group of scenarios were easy to write I started running into issues with the second group. The issues are twofold. Firstly I’m having to learn to rethink how I group my tests to fit into stories and scenarios. While working this through I started butting into problems with long class and method names which I can’t really shorten as there will, eventually, be literally hundreds of tests and I need to be able to distinguish between them.

After fiddling about with different ways of framing the stories and scenarios I discovered that its annotations aren’t picked up by the JUnit plugin for Eclipse so I can’t rely on them to make readable tests, I have to use readable class and method names.

Then, I discovered that Tumbler isn’t hierarchical. Stories are listed on the index page, then you can drill down into a story and see it’s scenarios. That’s it. If I had 100 stories I’d have to wade through all of them on the front page. What I need is epics.

This all rather makes sense for a tool that’s going to be used at a higher level, detailing 20 or 30 user stories that constitute an application, but I want the ability to test at different levels. After all, as I understand it, BDD can be considered fractal in its nature and is as easily applied to a users interaction with a save dialog box as it is to the save method call on some object somewhere. Yes, the players change, and yes the granularity and precision of the inputs and outputs change, but it’s the same fundamental thought process when developing the tests.

In order to shed some light on the issue I tool a look at the Tumbler source, specifically the test cases, but they were all at the user level. Tumbler itself isn’t that complicated a program so it may be that these user stories suffice for testing the majority of the code, but I want to know at an object level that they do what they say on the tin.

Sadly, the majority of this discovery has been performed on the train with its connectivity issues so performing research into alternative tools is proving hard. That said, given Tumbler isn’t massively complex I may just put my current project to one side, fork that and get it to work at both the low and high levels. In the mean time it seems like I need to do more research.

TDD, BDD and Sonar; or how I learned to stop leaning on a crutch

I should probably start by pointing out that this post is more to help me get something straight in my head than anything else. It’s also covering a subject that I’m not sure I fully understand, so I may have completely missed the point.

One of the things that I was most interested in at Sync Conf was Behaviour Driven Development (BDD). I’ve never been great at following Test Driven Development (TDD), mainly because I couldn’t make the shift required to fully get my head round it. What I practiced, if it has a name, was Javadoc Driven Development; each method would have descriptive Javadoc that defined what happened on various inputs. I found that by doing this I built up a narrative of how a class would work and that provided me with concrete test examples.

This method of testing only really works if you write decent Javadoc. The following is next to useless, and on many levels:

/**
* Sets the name.
*
* @param name the name
*/
public void setName(String name);

What happens if I pass in null? What happens if I call the method twice? Does passing a blank string cause issues? I’ve heard so many arguments that Javadoc is pointless and you should just read the code, after all, it’s just going to get out of date. I find that attitude utterly reprehensible; the behaviour of the method could rely on something that it’s calling and that could go more than one level deep. I don’t want to have to dive through reams of code to understand if what I’m calling does what I expect, nor do I want to have to guess. For me the Javadoc provides a contract for the method in a narrative form which is then implemented by the code. Change the logic of the code and you have to change the Javadoc, and I’d actually change the Javadoc first.

The mindset I try and put myself in is not “how will this method work logically”, but more “how will this method be used and how does it fit in with what the object is trying to do”. In the above example we’re setting a name. Does it make sense for a name to be null, or blank? If we can have an empty name how is that represented? null, empty string, or both? Is a blank string treated the same as an empty string? Should we trim the string? Are there other things we’re going to limit? You then document the answers to those questions:

/**
* Sets the name to the given value, overwriting any previous value that was
* set. Passing <code>null</code> into this method will have the effect of 
* clearing the name. Passing a blank or empty string will have the effect 
* of clearing the name by setting it to <code>null</code>.
*
* @param name the value to set the name to
*/
public void setName(String name);

All of a sudden you’ve got a load of things you need to test. I’d be writing tests to ensure that:

  • Given a null value, providing a value A set the value to A.
  • Given a null value, providing a null value retained the null value.
  • Given a null value, providing a blank value retained the null value.
  • Given the value A, providing a value A retained the value A.
  • Given a value A, providing value B set the name to that value. 
  • Given a value A, providing a null set the name to null.
  • Given a value A, providing a blank string set the name to null.

Those of you familiar with BDD may already be seeing something familiar here. What I have been doing is something very similar to BDD, albeit in an informal and haphazard way and at a very low level. I was defining functionality as a narrative in the Javadoc with my user in mind (another developer), and then using that to discover the scenarios that I should test. I was actually so used to this method of working that when I used Tumbler to test one of the classes I was working on it already felt natural and the tests practically wrote themselves. Interestingly enough the conventions used by BDD and Tumbler freed me from one of the constraints I was facing with testing; that of my test classes were getting too big. I will still structuring my tests classes as the mirror of my code, so for any object Foo there was a FooTest. By thinking in stories for the tests too and grouping scenarios that belong to a story I could break out of this habit and have as many classes as I needed testing the behaviour of Foo.

Happy with my new test scenario, and the output that Tumbler had produced, I proceeded to run Sonar against it. Sonar did not like the result. Most of what it complained about no longer matters. I can turn off the requirement for Javadoc on all methods because my test methods contain the scenario in the code and don’t require it elsewhere. The need for a descriptive string in my assertions can also be turned off as the way the tests are displayed by Tumbler provide a much more natural way of reading the test results. One critical marker stood out though: 0% code coverage.

It took me all of 30 seconds to work out what was going on. Tumbler uses its own JUnit test runner, produces its own reports and isn’t spitting out the files that Sonar is looking for and so there’s nothing for it to report on. This may or may not be something I can fix, although Google is yielding nothing on the subject. This got me to thinking: Do I need to know my coverage? Surely if I’m defining the behaviour of the class, then writing the code for that then I’ve pretty much got 100% coverage since I shouldn’t be writing code that produces behaviour that hasn’t been defined. This is where I got stuck.

Liz Keogh, who gave the Sync Conf BDD talk mentioned that BDD didn’t work so well for simple or well understood scenarios. Should I be using TDD here? That way I’d get my test coverage back, but I lose my new way of working. Finally, after much Googling I can across this blog and came to the realisation that I’m coming at this all wrong: there is no spoon. What I think Liz meant was that BDD at the level of the business helping to write the scenarios isn’t useful for well understood scenarios, because they’re well understood and anyone can write them, not that we just give up on BDD and go do something else… or maybe she did, but if I’m understanding Hadi correctly then using TDD instead of BDD is just a semantic shift and I could just as easily use BDD in TDD’s place.

We all know that 100% test coverage means nothing, and that chasing it can end up an exercise in pointlessness. Then there’s the farcical scenario where you have 100% test coverage, all tests running green and software that doesn’t work. So why the panic over not knowing my test coverage? I think it boils down to the Sonar reports let me browse the code, see whats not tested and then think up tests to cover that code. In other words chasing 100% (or 90% or 80%) and writing tests for testings sake. If I’m doing BDD properly then I’ll be thinking up the narratives, determining the scenarios and then writing the code to meet those scenarios. If my code coverage isn’t above 80% (which is a level I consider to be generally acceptable) then I’m doing something wrong as there is code and code paths not covered by scenarios which is, in theory, pointless code.

So how do I solve my Sonar problem? Simple, unhook the alerts on test coverage, remove the test coverage widget and keep my eye out for a plugin for Tumbler reports. In the mean time I can just use the reports generated by Tumbler to keep an eye on my tests and make sure they’re running clean and read up on getting my Maven builds to fail when Tumbler has a failed test.