Is Your Code Worthy Of Being Improved

ExplicitYou know that feeling you get when you open up a piece of code you’ve never seen before and it’s a complete and total morass of crap. It’s that sinking feeling in your stomach when, no matter how big your screen is, the code just doesn’t seem to fit. You don’t get even a glimmer of indication of what the code is meant to do by giving it a quick skim and the unit test are, if anything, worse than the code (crappy unit tests are worse than crappy code). You know you will need to start at the beginning and go through this sucker line by line to pry even a semblance of meaning out of it. I really hate that feeling and I hate the people who make me feel like that (of course I don’t really hate them, but you sure do wish you could go all Homer Simpson on them – when he chokes Bart – just for a couple of minutes). What I would hate most of all though, is for someone else to feel like that about me and my code.

We’ve all heard that old maxim about leaving code in a slightly better state than when you found it, but you know what, sometimes you feel like the code is so disgusting that you just want to get out of there as soon as you can. It’s a bad situation for a piece of code to end up in, not conducive to being improved, not worthy. And I am well aware that sometimes, depending on what you’re working on, it is damn tough to write pretty code. But, here is the way I view it, at the very least, your code should be worthy of improvement! I want people to feel at home when they look at my code, but failing that I’d like them to not immediately want to throw up when they come for a visit. In my mind it all starts with being explicit.

Being Explicit When You Code

We all have our little quirks when we code and for the most part this is fine, but there are certain conventions that tend to clarify the meaning and we should all endeavor to adopt them if we can.

  • descriptive variable names – it is not that difficult to use full words, we are not writing assembly code. So everything will be a little longer, but – fPtr vs. filePointer– which one is easier to understand? Maybe both of those are pretty clear, but what if you have a fullyAutomatedWidgetFactory vs. flAutWidFact, all of a sudden the sailing is not as smooth.
  • descriptive method names –  ditto for this one, make the method name tell the story of what it does (do I even need to mention class names that make sense)
  • structuring, classes and method in a way that makes sense – private and public methods mixed together in classes, classes themselves broken up along arbitrary boundaries. It takes very little time to extract chunks of code that have a relationship and make sense (when you refactor) and you will understand your code better yourself.
  • classes of reasonable size – this one is just a no-brainer, if you need to scroll for 5 minutes to find anything, it’s crying out to be split up and simplified.
  • methods of reasonable size – another no brainer, if it can’t fit on one 19 inch screen, it is long overdue for a refactor (and I am being extremely generous).
  • no long trains of method calls – chaining 20 method calls together – not a good idea. It might make perfect sense to you because you know the code, but to someone else it is just groan-worthy. Be sensible, have some compassion for your fellow developers.
  • etc.

There are dozens more I can list, but seriously, it if looks bit suss it probably is! Sometimes following some of these will actually prevent you from using all the funky features/shortcuts of your favorite language, but I believe it is a small price to pay for a little bit of extra clarity and readability. And I am aware that most of those are basics and yet so many people just don’t do it, which is just not nice. Not nice for those who have to maintain and modify the code later.

Using Technologies That Obfuscate Meaning

Sometimes in the interests of being cool and cutting edge or simply because it seems like a good idea, we use technologies that obfuscate our code beyond the level that anyone should reasonably be forced to endure. Here are my two pet examples of this phenomenon.

  • Spring Autowiring – I can’t really think of a situation where this is a good idea. Sure it might make wiring up your integration tests a little easier, but only in the short term. Wait until half the people on your team are new and see how much they like it.
  • Aspect Oriented Programming (AOP) – don’t get me wrong, the idea of AOP is just great. And to be honest there are a some specialized situations where it is a good idea to use it judiciously (transactions, security etc.). But, use it without thinking and you make your code an order of magnitude more complicated than it has to be. It was designed for a purpose don’t try to retrofit it into somewhere it’s not meant to be.

Every time you’ve got a new library you want to try out or want to make your code a little bit more ‘hip’, stop and think. Is it adding to the clarity of the solution or detracting from it? If you had to come in and work with this code would this make your life easier or harder? If the answer is harder, find another way to do what you want._ This is software, there is always another way_, and if it happens to be a little bit more verbose, well maybe that’s fine. If the verboseness is adding readability, then bring it on.

The Other Side Of Convention Over Configuration

Convention over configuration is great, I have nothing against it. When we all use the same conventions it makes everyone’s life easier. But what happens when the convention doesn’t suit your needs any more and you have to break it? The more you do this the dirtier and ‘hackier’ your code will seem to those who are used to the convention. So, if you’re working within a system where convention over configuration is the norm, think long and hard before you have to break the convention. Perhaps if you find yourself doing this often early on, it may not be too late to make a different technology choice, where the conventions are not as strict. Of course, sometimes you will not have the luxury, in that case do try to stick to the convention, diverge only when you have no other choice. Always remember to think of those who will come after you when you make decisions, after all, you probably want them to think of you when they make theirs.

These are just my thoughts, to me, being explicit is important. You might have different ideas on what constitutes ‘nice’ code, but if you get nothing else out if it I hope you will at least agree with this. The way to get others to leave your code in a better state than they found it, is to make it worthy of improvement in the first place! If we all strive towards that, ultimately, everyone will be better off for it.

Image by wanderingYew2

Is Basic Authentication Really Insecure?

The other day I was thinking about basic authentication. You know the one, the most simple authentication scheme built into the HTTP protocol, and it struck me that it has undeservedly been getting a bad rep. Ask anyone – who is in the know – about basic authentication and the first thing you hear would probably be the fact that it is insecure (it is basic after all). But is it really? Lets examine the facts.

It’s Only As Secure As Your Transport Mechanism

Just because we store something in plain text (or base64 encoded) does not mean it is inherently insecure. When we get the users credentials we want to safely (without anyone stealing them) be able to transport them to where we are. You can think of it like transporting gold (or at least some sort of precious object) in the real world (meatspace :)). We normally try and protect our gold when we transport it, by putting it in an armored vehicle and maybe having a security guard or two around. We certainly don’t load our pickup truck full of bullion and ask our cousin Billy to shoot it down the east coast. A similar situation applies when it comes to user credentials. It does not matter what form the credentials are in (plaintext or not), what we really need is a secure method of transportation.

This is why we have HTTPS, right? When we want to protect against eavesdropping, we use a secure protocol. When we want to protect against stealing, we use a secure transport. Sure we can melt out gold down and combine it with lead (and then figure out some way to pull them apart later), that would make it harder for people to get at it if they steal it. But we already have a secure transport, so perhaps that might be overkill. In similar vein we can get the credentials a different way and then obfuscate them somehow (encrypt) before we send them down, but we already have a secure connection – so overkill again? End of the day you don’t really care about the security of the credentials, you care about the security of the connection over which the credentials are transported.

What If The User’s Machine Is Compromised?

Well in this case, no matter what you do you’re pretty much stuffed anyway so worrying about it is pointless. You can’t really control what goes on with the user’s machine. If malicious code already resides on the machine the user can say goodbye to his credentials (and to whatever the credentials are protecting). A simple key-logger or trojan will defeat the most brand-spanking-awesome crypto-obfuscation system you can think of, unless the user is particularly savvy. Even a secure connection matters nothing in this case as the credentials are compromised before they are transported.

The point here is, figure out what you need, as far as secure connections go, and why you need. Chances are, you might find that basic authentication may serve your needs. It is not the authentication scheme that is insecure, it’s how you implement it!

The Lord Is My … German Shepherd? WTF?

German ShepherdThose who know me, know that I am not particularly religious, so when I feel like engaging in some creative blasphemy, I just go ahead and do it :). Here is the result of one such episode. What I did, was take Psalm 23 – “_The Lord Is My Shepherd_” (I think it was 23) and made slight modifications. I like German Shepherds, great dogs in my opinion, but I reckon that – sheopard – would be a much better way to spell it, gives it a certain zing. Anyways, I must have really needed a creative outlet at the time (I get that once in a while, must be an undocumented side effect of writing software), cause this is what I came up with :).

Lord Is My Sheopard

“Lord” is my sheopard; I shall not want – **another sheopard

** He lieth down in green pastures

and I leadeth him beside the still waters – **he is afraid of running waters

** He restoreth my soul – after a hard days work

He leadeth me on the path of rightness – **when we go walkies

** for his name’s sake – **we live on Lord’s avenue, funny that

** Yea, though I walk through the alley full of shadows at night

I will fear no evil: for though art with me – **he is a big freaking sheopard

** Thy big teeth and paws they comfort me – **noone is gonna mess with a big sheopard

** Thou sits at my table in the presence of mine enemies – **makes them nervous

** Thou put thy head into thy bowl – **has a big appetite as well

** Thy bowl runneth over – **hmm, should probably get a bigger bowl for him

** Surely goodness and mercy – _**that’s what my enemies will cry

**_ shall follow me all the days of my life – **try being mean to someone with a big sheopard for backup

** and I will dwell in a house with “Lord” for ever – unless they try and kick us out, but they probably wouldn’t dare, you try kicking a big sheopard and see where that gets ya

Well, there you go, now it will live on forever on the interwebs. All hail the Sheopard!!!

Image by Maurice Koop