5 Destructive Mistakes to Avoid When You Create a Shared Code Library
Learn from the mistakes of a rookie programmer writing his very first library.
A little Background: For work I was asked to write a C# library that implemented the use of modern Artificial Intelligence Speech-to-Text APIs. I had never imagined that I would write a library or thought that one day someone might use mine before being given this task. The whole assignment was a whirlwind. I learned extremely relevant coding principles while also having to arduously fix my mistakes along the way. Here are the six most time consuming mistakes I made the first time around, so that you can avoid making them in your next project…
1. Thinking you will get it “right” on the first try
The first and most important thing I learned while writing my library was that my perception of time is skewed. If you think your library will only take a week to write and test, think again. I recently read an article on estimating project time frames I found on Hacker News, and in it I found a perfect description of my own experience
I wrote and deleted 295,181 lines to produce a final output of 26,571 lines. That’s a ratio of more than 10:1! For every 1 line that got published, I actually had to write 10!
This exclamation was originally in the context of a book published by the author of the article. Yet he goes on to explain that after reviewing many GitHub repositories he found the amount of lines of code that are re-written versus in production is at least in a 10:1 ratio. That means that you could write 16, or even 20 lines of code for each line in the final polished project. I can say without a doubt, that if you are going to undertake writing your own library that you will experience a similar trend. There are two major things you can do to speed up the cycle of writing, re-writing and condensing. First, put yourself in the mindset that once you have working code that performs a given task you have only accomplished half the battle. This way you put more emphasis on the editing and review of your code as you write, rather than just finishing the functionality and having to backtrack to refine syntax mistakes.
2. Picking what language and software development kits (SDKs) you decide to use
The second most important thing to realize before you start writing any code is that the tools you choose to use matter, a whole lot. If you start writing your code in a language which does not support certain features you want to add down the road then your library will never reach its full potential. If its full potential is never seen or mapped out you can also bet that a lot less people will use it! The best way to avoid this is by front-loading the difficult research to understand what you want this library to evolve into, and what base functionality you want it to have.
For example, when I wrote my first library I was utilizing five different AI APIs from four major providers: Amazon Web Service’s Transcribe, Microsoft’s Speech API, Microsoft’s Video Indexer API, IBM Watson’s Cloud Speech-to-Text API, and Google Cloud’s Speech API. Initially I thought that I could simply just integrate all of them easily as they should all just have easy to use endpoints I could call to receive the data I wanted back. However, this proved to not be the case, as many of them were very easy to use only if you used their SDKs. After realizing this I thought hmm, maybe I can just use all their SDKs then? Turns out this is one of the fatal mistakes I made, as not only did my clients have to import all these SDKs to use the final library package, but I also had to find a common framework that all the SDKs ran on. This inherent problem cause me to have to change the framework I was writing my code in. I had originally started off writing it in .NET Core (essentially a cross-platform compatible and extremely portable version of the .NET framework) but as one of the SDKs only supported .NET I had to switch and write it in .NET 4.6.1. In doing so I lost a whole lot of portability, as my library could no longer be used by developers on Mac or Linux boxes programming in .NET Core. So due to that simple misunderstanding I had before writing my library I lost a ton of potential users.
The best way to avoid making this mistake is to always develop in a widely supported language or framework and make sure you do your research based off of what languages your APIs inherently support. If you really want to make sure there are no hiccups go back to the basics and use JavaScript as all these frameworks do is essentially generate JavaScript code. This will be more tedious but doing something right the first time is a lot easier than going back and having to do it again, especially after forgetting what you did in the first place.
3. Learn and Implement Design Patterns (Use others experience…)
The very last thing I recommend before diving in to writing your library functions is to learn or review your design patterns. A design pattern is simply a high level abstraction of code used to solve a commonly occurring problem. For instance, if you create a very simple 8-bit video game then when the game starts your program must draw all the objects on the screen. As programmers we know that we can have this done when the object is instantiated via a constructor. However, did you know that there is a design pattern called the “factory pattern” that details a way that you can instantiate all your objects from the same place? Instead of writing…
var MainCharacter = new Hero;
var MainVillian = new Villian;
var LevelOne = new firstLevel;…you could call the create() function from a factory you made (based off the design pattern blueprint) and use it like so…
var MainCharacter = Factory.create(hero);//This function can be used with ANY object in the game however //unlike abovevar MainVillian = Factory.create(villian);
var LevelOne = Factory.create(firstLevel);
var VictoryKey = Factory.create(key);
var VictoryDoor = Factory.create(unlockableDoor);
It might not look to you like you saved much code by doing this, and in a way you would be right, however that is the magic of design patterns. Design patterns represent years of developer experience, and maybe they aren’t apparent to your small 8-bit game as the scale is tiny. Yet, if you are looking to develop a project that will expand and grow as the needs of its users grow then design patterns are exactly what you need to organize your code. It not only allows for easier fixes when things go wrong and don’t build, but it also lets you modify it much more easily. On top of that it also makes reading the code easier for other programmers as all objects and how you instantiate them can be encapsulated by the factory.
In my experience I found the factory, singleton, and strategy patterns to be very useful. I used the singleton pattern while writing to files using stream-writer in C# to make sure everything was done in order even if called from multiple threads. I used the strategy pattern to implement each APIs services, so a user could switch between using Google’s, Amazon’s, Microsoft’s, or IBM’s speech-to-text. (This also allows for incorporation of different providers down the line!) I also chose to use the factory method to instantiate a client for using the library and creating/disposing of which AI service suite they want to use.
4. Beware the Copy and Paste Mentality! (…but not their code.)
Along with this idea of using other programmers experience comes the temptation to copy and paste work that is already done out there. This can be beneficial if you re-use only what you already understand, and give credit where credit is due. If you use a design pattern make sure you understand what the advantages are to using it, because for every advantage there is also a disadvantage. The real benefit of all these high level programming concepts is only when they are used in unison. So if you see another programmer out there making a library that has similar functionality to your own and you want to use some of their code, follow these guidelines:
First, make sure that it is code that you can use! This means checking the license on their GitHub repository and if you are not able to find any mention of open-source, contacting the actual developer themselves and asking for permission.
Second, make sure that it is applicable to what you are currently trying to accomplish. While there might be great code out there for using AI services I knew that there was no code out there that would fit my exact purpose, to make a very modular solution. In understanding this I saved myself a lot of hours of skimming code that would eventually of ended up being useless. (A very good step to avoid this is know what exactly you are coding)
Third, if you can’t find anything out there to help you don’t get discouraged. Not only is it a big world, but if you are the first to do something than that proves you are really making strides in providing your work to others. This is a positive, as it means what you are working on hasn’t been done before. While the concept of AI has been around for ages, very few people know how to use it and I felt this sensation multiple times as I tried to search for code snippets to help me along the way.
5. Choose how you distribute your library just as informed as you chose the foundation for it
The last thing to do before writing your code is to make sure you have a way to deliver it efficiently. You wouldn’t want to write all this code and realize that there is no good way to have other programmers call the library from within their applications. This can be achieved by researching what package managers are compatible with the framework you are writing in, or by creating a GitHub repository with extremely detailed documentation.
Because I wrote my project in C# I ended up using the NuGet package manager as my delivery system, since I already had limited my delivery scope to just .NET 4.6.1. However, this was one of the few areas that I had already decided before starting the project so I had less trouble setting things up. The most important thing to watch out for is that if you use SDK packages you have to list them as dependencies for your final NuGet package. (or any other package manager such as developing on node.js with npm as your manager) This is also where you will find all the framework choice mistakes as the SDK packages you use must all share a common framework and then your final package must be the same framework.
In Conclusion
While all these mistakes are important to keep track of, remember to not lose focus on the scope of the project. If you are writing a very small library with limited functionality and you know exactly who will be using it, then perhaps your decision making process in regards to design and delivery will be much quicker. If you learned anything from reading this article it is to think like a programmer the very first thing you need to change to improve your development skills is not what you code, but how you think about designing and delivering you code to reach the largest or a target audience.
