How To Write Public Interface That Doesn’t Make Amateur Developers Cry
Sometime in coding, clarity and accessibility of the code is overlooked. This is understandable: if you’re in crunch time, most of your energy is spent on getting the code to work, not to look neat. Unfortunately, when programmers create tools that are intended to be used by other people, an unclear interface can make tools less effective, if not unusable. A large goal of tool creation is often to increase the speed of development for others; instead of reinventing the wheel, they can simply build off of the powerful code you’ve already created. But if the tool’s learning curve is too steep, it can take away from this purpose, as the time the user would have spent recoding the functionality, instead of being truly saved, is spent attempting to figure out how to use the code. This issue can be mitigated by spending time to make sure your tool’s interface is clear and accessible not only to you, but to programmers with less experience and less familiarity with the area.
Naming Conventions
Naming conventions often get a reputation of being superficial. While “this convention vs. that convention” decisions absolutely can be arbitrary, having a consistent naming convention is important, as the better the naming convention is, the less time your user has to comb through your documentation. Ideally, if your user doesn’t know the exact name of the function or class that they’re looking for, they should be able to make a decent guess; at least a good enough guess they can efficiently search for it in your documentation, or recognize if a system like IntelliSense suggests it as an option. Naming conventions help with this. More specifically, if, for example, you give similar functions similar names, a user might guess that if the function for something like scaling a cube is called “Cube->Scale,” that the function for scaling a cone is “Cone->Scale.” If you name cube’s function “Scale,” but cone’s something like “Multiply,” you will likely annoy the user, as there is now unnecessary information for them to memorize and it takes longer than needed to figure out how to operate the cone the way they can the cube.
Similarly, giving two things that do dramatically different things similar names will likely annoy and confuse the user. If “Add” on an object called “List” means to add an item to the list, but “Add” on “Catalogue” means to add two catalogues together, there’s a good chance your user will accidentally use “Add” to try to merge two lists, or to add a single item to a catalogue. This makes using the interface take longer then it needs to, undercutting one of the main purposes of tool creation: to increase speed of development. In the same vein, its helpful to give things meaningful names (as opposed to names like k1, k2, func(), temp, etc.). When variables have meaningful names, even someone unexperienced with coding can get a vague idea of what’s going on in a given piece of code by glancing at it, which makes communication between teams of multiple programmers much easier.
Account for Murphy’s Law
Your program works perfectly, as long as people are using it correctly, so you’re done, right? Unfortunately, users can and will use your program in ways you didn’t intend. The important thing is to make it harder for the user to screw up, or at least to make it so their mistakes are easily fixable. Part of this is being meticulous about data encapsulation and const correctness. In other words, if a user has no reason to directly change a certain value or object, use whatever functionality your preferred programming language gives you to prevent the user from accessing that data or performing those operations. Even if your user does have a reason, if the user putting in nonsense data will cause harmful ripples through the program, use getter or setter methods to make sure any alterations the user makes are reasonable.
The other part of acknowledging Murphy’s Law is error checking. Your program cannot, and should not, continue running with all forms of unexpected input. Instead, have your program verify it is working with valid data where its applicable, and importantly, give a clear and concise error message to the user when something is amiss. If the user is dealing with a large program they’re unfamiliar with, the program simply crashing without useful error messages tells them nothing about where to look for the error, and that makes debugging for both your user and you take significantly longer. While no one can predict every possible thing that could go wrong in their programs, there are some common places errors like this could happen: specifically, whenever you are relying on information provided by the user or other external sources, and whenever you are relying on aspects of the computer you don’t have direct control over, such as available memory.
Talk To Users
When working on a project, often information that well-known amongst experienced programmers, the company idioms, and specific program features become so familiar they feel like common knowledge. This can mean that when the tool is released to be used by the public, its documentation is missing information that the average user would not reasonably know, as that information felt self-evident when the documentation was written. One solution to this is to not only test the program in terms of its output, but to test it with its intended audience. Watch someone else use your program, preferably someone who didn’t work on it, and notice where they slow down and get stuck or confused. Pay attention to any type of feedback you get, and to the questions you are asked. This is particularly important if you are making any sort of inter-disciplinary tool or one intended to be used by people who aren’t programmers, such as an asset pipeline.
In conclusion, its important to remember that user experience still matters when making tools intended to be used as additions to code projects, as opposed to elaborate GUIs. Having intuitive code can dramatically increase how quickly someone using your tool can program with it, as well as making it easier to debug your own code. Code that can be easily read and understood by people with less experience is a virtue in code that is often underestimated.