Oh, What a Surprise!

Who doesn’t love a nice surprise?

Sadly in software engineering a surprise is seldom nice. I like to use the word surprise to describe the things which make you check that you’re seeing what you’re seeing in the code. Essentially, the best code is self-explanatory and done in a way which doesn’t cause someone to wonder how this sort of thing came to pass.

Avoiding Surprise

  • Find how it’s normally done
  • Obey good conventions
  • If you deviate from conventions, deviate in the direction of common alternatives
  • Be aware that names are taken literally, so name things appropriately (avoiding things like The Lying Get)
  • Invent when you need to and reuse when you can
  • Don’t be self-servingly clever
  • Don’t implement for scenarios that will never happen

When It’s Just Surprising

There are reasons why things ought to be surprising:

  • Using a technique that’s new to your team
  • Working around insurmountable obstacles
  • The request was really unusual

In these situations, you should leave decent explanation behind. You should have clear documentation and you should be aiming to explain the unexpected in terms of WHY not WHAT.

2 comments

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s