When carpenters go onto a job site, they bring their tools. Some of them have so many tools, they bring the truck and the trailer. They instantly set up shop and start building without tool dependencies.
I've worked as a contractor for most of my IT career. I fell into it by accident, taking a job offer for a contracting company due to my immediate need at the time. It's clear that companies want contractors for a number of reasons and the goodness of it for the programmer is this:
We must always keep upgrading our skills.
This is how we stay employed in the fast changing IT world.
I've worked for many major companies. Only one of them had a fantastic reusable API. That company was IBM. They produced APIs for customers, but carried the same concepts to their own OS layer(s) where everything was discoverable.
Must Be Exposed
If an API is un-discoverable or unknown, it doesn't get used. There are many tools today that help make creating them easier. Today's best tools all expose the APIs via HTML. Two such tools are Swagger (for ASP.NET backend), and CompoDoc for Angular (frontend).
Here's an Example of CompoDoc for Angular
If we use naming conventions as shown in the image above, we are able to learn all the internals of our reusable code merely by knowing where we are in the code and what we want to accomplish. In the image above we used the following conventions:
- All reusable bullet-proof functions start with the letters func. The allows intellisense to show all functions in the project.
- The next two or three areas relate the function to a specific component or "speciality"
- The remaining text is for drill down.
- Intellisense in VS Code or Visual Studio is the discovery tool.
e.g. We want to create a "Postable" address.
- funcADR gets us to the reusable address functions
- funcADRp Will show us all reusable post functions in the ADR module.
- We pick funcADRPostableAddress
- As soon as we type the open bracket we see this:
- If we don't know how to use it and want to see examples, we just right click and select "find all references"
This makes using JSDOC important. It allows future developers to cut the time in getting to know the API. The better it's documented the quicker they will understand it.
ASP.NET has the exact same concept, where code comments are used for the API documentation.
APIs from the Web Site
The advantage to seeing the API in a web site, is that it allows both high-level overview and a drill-down into details. By using naming conventions as mentioned earlier we've been able to mock this ability using intellisense and specivity rules.
Either way, it's all good and a further enhancement to our software assembly line. Remember, never ever do it twice, it's way better to put it into a reusable library as soon as it's needed twice. Start your libraries today.