Code Renaissance is about building great teams and great software. By exploring best practices, team interactions, design, testing and related skills Code Renaissance strives to help you create the team and codebase that you've always wanted.

Program like Hansel and Gretel: Leave a Trail

There's a lot to be learned from the story of Hansel and Gretel (like don't be evil or you'll get shoved into an oven) but the main thing that developers can take away from the story is the importance of leaving a good trail.

Here's the ultra-condensed version of the story:

  • Times are hard and there's not enough food for the family.
  • The children's father takes them in the woods and leaves them to die.
  • Fortunately Hansel left a trail of stones and they get home safely.
  • Again father takes them deeper into the woods and leaves them.
  • This time Hansel left a trail of bread and it gets eaten by birds.
  • Without a trail they're lost and get in a lot of trouble with a witch.

At this point you're wondering where I'm going with all of this, let me explain.

I'm living with a code base that uses a lot of very complicated code to do very simple things. It's not everywhere but there are several areas, mainly written by an overly intelligent former team member, that are pure hell to find your way through. You're stepping through the debugger and then... nothing. Something magic happened and the debugger didn't step you into it. There's no trail to follow; you're lost.

These nasty sections of code are the woods.

Something as simple as adding a few values to a drop-down means you have to trace back through six layers of javascript, including several callbacks and a proxy object, 5 layers of c#, a stored procedure and some nested SQL functions all to find out that a simple table change in the database was all that was needed. Wouldn't it have been nice if someone had left a comment saying "To change the values in this drop-down edit table x... oh and reset the app pool to get the changes to show up".

Lesson one is that if you're one of these hyper-intellectuals who enjoys building logic puzzles in code, don't. Instead design things so that there is an obvious trail through the code for us mere mortals to follow. I know, I know... simple is hard; let that be a challenge for you.

Lesson two is that as you find yourself hacking your way through the woods and get to know your way around, leave copious trail of comments for others to follow. Your team will thank you for it and who knows you may find your way through here again some day.

Lesson three is that not following lessons one and two is evil and evil people get shoved into ovens at opportune times... you've been warned!

Confession time: I worked my way through that nasty drop-down code on Friday and was so worn out when I finished at the end of the day that I didn't comment it. Come Monday I'm going to trudge back through there and leave detailed comments in the sections of code where the trail ends. Time to practice what I preach.

0 comments: