admin
As a software contractor – or as I say to my parents, consultant – I’ve discovered several natural rules over the years. You can learn them the hard way, or you can read my blog. This is The First, Top and Most Essential rule of software contractng.
Consultant’s Rule 1: If it’s not broken, don’t fix it
As a contractor, you’ll regularly arrive in a new company, with a whole new lot of code to mess around with. Monolithic. Archaic. Spaghetti. All terms that could apply to many mounds, sorry, heaps of code you’re likely to encounter.
The temptation is to fix it. Now. At once, and everywhere.
Don’t.
I see newbies do this all the time. I’ve been there myself. “Oh, these thirty lines of code are repeated here. And here. And…here…and here OMG who WROTE this?…and here…I know, I’ll pop them into a neat little function and call it from all over the place.”
Sounds like a good idea, right?
Sure. If you missed any little breaking differences across the twenty implementations, your mistake will be picked up by the automated unit tests.
Um, what automated unit tests?
Some companies do indeed maintain automated unit tests, and even run them occasionally, but are the tests documented? Do they cover the code you’re planning to change? All of it? Every possible instance?
TBH, in a contracting situation you probably don’t yet know how to run some of the classes you’re planning to change – no idea how to get to the place they’re called from at runtime – do you have time to research and test twenty different use cases? You only managed to get the code building yesterday. Oh and by the way, What are you actually SUPPOSED to be doing? Easing your way into the software by fixing a priority 3 bug…so why are you changing a file in a whole different module?
‘So. What?’ you ask. I’ve got to leave that stuff there, steaming gently, waiting for the next idiot to break it instead?’
No. Here are your options:
Option 1
Point out the issue to your boss and ask for permission to change the twenty instances you’ve found, replacing them by a simple function call.
Likely Outcome
Good luck with that. They didn’t hire a contractor to refactor their code to perfectly match the structure recommended in universities. They know the software is kludgy, but it seems to work. They hired you to implement some new feature, or expedite a release that they consider business critical. There isn’t time to test your changes. Oh and by the way, your boss probably wrote some of the code you’re dissing right now.
Note, though, that this is the correct approach if you’ve identified an issue which is causing or is highly likely to cause a serious bug.
Option 2
Don’t say anything to your boss, who looks rather busy. Just go ahead and do it, you’re a professional, you won’t make any mistakes.
Likely Outcome
Sometimes you’ll slip your changes through, but generally you’ll break a piece of functionality you didn’t know existed. Best case, you’ll delay a release. Worst case, you won’t delay the release and the first your boss will hear about your bug will be from floods of irate customers. Your name will be mud. How much are they paying you again?
Option 3 (for refactoring code that currently works, this is what I recommend)
Do things right for the particular bug or feature you’re working on. Create the function even though you’ll only call it once. Pay attention to function parameters, and to where you locate the function in the code, so it’ll be easy to reuse later.
Optionally, insert a todo comment in all the places you’d like to call your new function from, mentioning this useful function and where to find it.
Commit your fix / feature and tests.
Bide your time.
Likely Outcome
Later (maybe even six months later) you’ll find yourself working on the areas of code that would benefit from your super-cool function. Off you go. Delete all those useless redundant lines. Call your function instead. Your changes will (hopefully) be tested, because they’re in an area you are in fact supposed to be changing.
As you settle into a new job and become more familiar with the application you can relax a little. You’ll acquire a better grasp of implications and you’ll have some kind of automated test regime in place. (Won’t you?)
Eventually you should be in a position to make sweeping changes with confidence.
Conclusion: Refactoring is wide-ranging and incremental. You can repeat Option 3 above over and over again, until the code base is full of improvements and most of them are in use.
Guiding Principle: Never change anything without having a comprehensive test plan in place.
On Tuesday 4th November I gave a talk on the People’s Stage at the Dublin Web Summit. ‘The Dos and Don’ts of Consulting’ was my theme. After nearly twenty years at the coal face, I figure I qualify as an expert.
I had great fun.
Unaccustomed as I am to public speaking, it was brilliant to give it a bash in a safe environment. The People’s Stages are small and frequented mostly by passers-by, who avail of the free chairs while they plan their day.
I expected most of my audience to be either distracted or half asleep. If I huddled over the podium, muttering into my notes, they would probably start snoring. I knew I could do better. I’ve been lucky enough to see fantastic speakers who know how to hold their audience – Joel Spolsky, Herb Sutter, Cindy Gallop.
Channelling ‘gripping-speakers-I-have-seen’, I created short, one-or-two-word slides with lots of pictures, and memorised my talk so that I could fix attendees with a beady eye.
It was a real triumph. By the end of my allocated seven minutes, most of those sitting in front of me were looking up and giving me their attention. A couple of the volunteers laughed at some of my jokes, and the sound engineer said in astonished tones as I left the stage “That was really good!”
When an earnest audience member approached me afterwards to point out a suspected anomaly in my content, my happiness was complete.
In 2005 I had the good luck to be the first to spot a minor error in Scott Meyers’ classic book ‘More Effective C++’. He keeps meticulous records, so you can see the details here – search for 5/25/05.
This is my greatest claim to C++-Nerd-dom, but if you want more proof, I have actually read all of Alexandrescu’s ‘Modern C++ Design’. Even the bit on Symmetry with the Brute-Force Dispatcher.
I had this problem after we lost a domain name for a Joomla! site.
I copied the Joomla! site back onto the server using a new domain name, which allowed us to use the same database. There were two issues:
– I had to change some configuration settings, but Joomla! reported that it couldn’t save configuration.php. I ended up changing it via Filezilla.
– Virtuemart displayed nothing until it was configured to use the new domain name (see this post on that topic.)
Once I had the site running and looking ok I had to update the theme. This was impossible because of the write permissions issue. I couldn’t write to any location on the server via Joomla! I tried everything in this useful post, but no joy.
The website is running on IIS 6.
I found a setting on the hosting site’s control panel called ‘Website Write Permissions’, and ticked it. This fixed the Joomla! write permissions, but what else does it do?
Next step: update to the latest versions of Joomla! and Virtuemart, and urgently review site security.
I want to allow eager readers to sign up on my website to receive emails from me. I have a MailChimp account and my WordPress expert told me it would take five minutes to install a plugin that uses it.
Yeah, right. Not for me! I installed the plugin and supplied my API key and got this message:
“Uh-oh, we were unable to verify your API Key. Please check them and try again!
The server said:Could not connect (ERR 13: Permission denied)”
Frustratingly, a couple of people logged the same issue on the WordPress forum over a year ago but never received a reply.
I tried another MailChimp plugin – same problem.
The solution lay with my hosting provider. They block outgoing connections by default, but you can add them to a whitelist. Once I did this the problem went away.
If you compete in the TopCoder SRMs, the TZTester plugin is very useful. It calls all the tests for you and displays the results, saving valuable minutes in the arena.
I used it with my old computer but couldn’t get it working on my new one, and with the clock counting down, sod’s law was against me.
$RUNTEST$ and $TESTCODE$ sat in my template, stubbornly refusing to become useful C++ code.
The solution was simple – I found it here.
Just make CodeProcessor your default editor, instead of (in my case) popsEdit.
If your TinyMCE control isn’t appearing and just looks like an ordinary text area, check the tinyMCE.init({ syntax. Missing or extra commas or other syntax errors here will cause the init to fail.
When calling the MailChimp listBatchSubscribe method via PerceptiveMCAPI in ASP.NET, I got the followng error:
“A parameter is of, or contains an instance of, type CookComputing.XmlRpc.XmlRpcStruct which cannot be mapped to an XML-RPC type”
I panicked, thinking that the PerceptiveMCAPI, which up to now I’ve found flawless, might be broken for this one, vital method. Was it unable to process the Dictionary
After looking closely at my merge vars I commented out one that had a Decimal value. Everything magically worked. Replaced with a double and I’m back on track.
My ASP webpage containing a TinyMCE control worked in Chrome but was broken in IE9. Clicking the ‘Send’ button simply didn’t trigger the sendnow_click event, which I verified by putting a breakpoint in the debugger.
The solution was to remove a superfluous ‘form’ from the page.
I hope this post helps a fellow sufferer.
When trying to start my server in SQL Server Configuration Manager as usual, I got the message:
“The request failed or the service did not respond in a timely fashion. Consult the event log or other applicable error logs for details.”
I couldn’t consult the log because no log was generated today.
So, the solution was a bit embarrassing. I removed the password from my logon this morning. Apparently, SQL Server doesn’t like Windows logons with no passwords.
Once I added a password again, and typed it into the properties for the SQLExpress server, everything went back to normal. Phew.
