Mini-Catalogue of Stupid but Common Issues
Having been through another chaotic release today, with most of the issues looking strangely familiar, I thought it might be a good idea to write a quick post about these issues that are very common, and yet look utterly stupid once you have managed to fix it. Stupid because they keep coming back over and over again and they are easily avoidable. Heck, they even are easy to fix, but at the end of the day you’re the one who ends up looking stupid, because you’re the one responsible for the release…
All this will probably sound dead obvious to people out there, but you wouldn’t believe the number of times I still have to tackle that kind of stuff. So, with no further ado, here is this list of common issues that keep cropping up (you’ll probably want to add your own):
- Database changes: this would have to be right at the top of the list. Missing CREATE TABLE, default value not set, missing constraint, missing reference data, etc. Somehow, there must be an ideal way of handling database changes, but it hasn’t come my way and the projects I have worked on yet. In any case, database changes scripts must be kept up-to-date, in version control: new tables, new columns (nullable or not, please check; think of the default value, and think of what the existing records will look like), altered tables, new records (reference data). Make sure you backup the tables you either drop or alter1 . The db scripts must be tested along with the rest of the code and executed on a database replicating the structure of the production environment. When changing the Hibernate mapping files, make sure you update the database scripts as well, ideally in the same Subversion (or CVS, or whatever) commit. And vice-versa. When dealing with database scripts, anything that has been forgotten is a pain in the neck, as you have to go and haggle with the DBA to either get the permissions to execute that missing query, or to get him or her to do it. The more forgotten there is, the more you have to go to the DBA, and the stupider you’ll look. Or your team lead, for that matter, which is not good either.
- Classpath: Missing Jars, properties file, file at the wrong place, ClassNotFoundException2. Make sure your project is properly structured, with the properties files limited to the strict minimum and contained in very specific locations. Avoid crazy things like cyclical dependencies, make sure you know exactly which version of what jar is being bundled, and from where. Outsource your dependencies management to something like Ivy if it makes you more comfortable (but stay away from Maven if possible…). Try to understand how the classloading in the J2EE server you use (for example, in WebSphere, it helps to have some clue about what PARENT_FIRST or PARENT_LAST do…).
- Date/Time: Dates and time are a bleeding nigtmare. Especially dates. Look at anything involving dates/time with the same suspicion you’d look at, I dunno, a multi-recidivist rapist released because of a typo. Make sure you’ve taken into account leap years, time zones, daylight saving times, dates in the future, dates in the past, time of the day when comparing two dates (again, beware DST), locale. Make sure you’re consistent when displaying dates, when entering dates (use a calendar component if possible). Enforce strict validation rules. Learn to mistrust Java java.util.Date (Remember: January is month 0!), and consider using JodaTime. Don’t worry, you won’t need to be an expert in leap seconds. Make sure you know with wich date pattern you’re working with. Don’t confuse timestamps and dates, and check if it the time is populated in your timestamp, and with what value.
- Encoding: Funny characters appearing in a page, or stored in the database. Make sure you know which encoding is used in every single layer of your application, especially in the presentation one (for example, if you’re working in UTF-8, make sure the file is saved in UTF-8, sports a UTF-8 content-type, that the forms are sent as UTF-8, etc., etc.): property files, JSPs, classes, database, etc.
- NPE: For the love of God, make sure an object is initialized before using it. Don’t think things like “Oh, but it’s been there, then it must be here” without having though twice (take into account that the code might change in the future, and this assumption might not be true then). We all have hilarious storied of comments swearing that // This shouldn’t happen, and guess what, it happened. We all know the joke, laughed at it, but hey, we’ve all been bitten by it, one way or another.
Now, it all comes down to testing, obviously. This kind of stuff should never even reach a production box, for the simple reason that if the tests were carried out in a regular and controlled manner, these problems would be spotted early on. But there are always (good, according to the guy whose name appears against the incriminated line of code in the Subversion Blame functionality) reasons for something to slip through, and post-mortem analysis often show miscommunication has one of the root causes. Well, there you go, you’ve been told!
Edit: For the record, I have spotted the first issue in the new Weblogism design, and guess what? It is to do with the comments having no date set.
1 Yes, even alter. Dropping a column, and create a new one is not a rename, for example…
2 Note that this can express itself in all sorts of ways, so it can sometimes be quite a pain to diagnose, for example funky NullPointerException when calling a WebService/EJB, etc. Again, all sounds pretty stupid, but it happens all the time.
