Things I’ve learned about programming: Simple API

I’ve been a programmer for about 15 years. I’ve rubbed shoulders with some pretty smart people. I’ve also had the pleasure to work with people who can’t quite grasp complex programming tasks or methods.

I _used_ to be a little pendantic. Granted, there is the occasional dope who is completely worthless and drags the team down. More realistically, though there are people who are more skilled in other areas, but can’t seem to formulate a consistent programming model in their head. They can do basic functional programming, but anything as complex as a void pointer is beyond them.

I completely respect this. Depending on the situation, it makes sense to have a core of competent programmers who understand the most bizzare software. They hack together a complex system, erect an API your mother would love, and then protect the users from the monstrous insides.

I’ve gotten flak from this from software people before, but let me explain my situation: I work with people who can design analog electronics where the lsb is in nano-amps. Nano-Amps. The same hardware can scale to hundreds of volts or amps, depending on the mode. This person is excused from knowing more than basic functional programming. These engineers are fully capable of figuring out complex loading, oscillating, timing, and noise problems. I can live with some API restrictions.

I’ve violated every rule or good idea I’ll put forth on this website, but here are some rules I can live with (C++ centric):

  • Replace anything with an index with an STL class or equivalent. std::Strings instead of char[] arrays, vectors instead of int[] arrays, and any number of multidimensional classes.
  • Replace for loops with for each loops. I know, it sounds trivial, but I’ve seen people fiddle with the conditional term on a for loop trying to get it right. Guessing to get it right. If they use a for each loop, they can skip iterators, and focus on getting simple tasks done.
  • Don’t use variable length function signatures, unless you are creating a wrapper for an existing function such as printf, or the like.
  • Opening a file, printing to a file,  and printing to the screen is hard for some people. Build them some tools that do both. Make sure they never have to see a pointer.
  • Don’t ever put preprocessor #ifdef statements in between { } brackets. 
  • Keep your functions below 20 lines. This isn’t even close to achievable, but it’s a good design goal. Once a function starts getting too long, it gets hard to understand. 

Some of you may be reading this and thinking that this is obvious. The rest will be thinking that I’m overly dumbing down the richness for the few. The thing that I’ve seen cost the most is code maintainence. 

I can build really awesome code, but when I move on because I’m bored and a hardware engineer has to decypher my code, I feel nothing but pain for them.

I’d rather leave my coding ego at the door and leave some code that is easy to change.