I've been thinking a lot lately about all the small utility apps I've programmed over the years and how I could have designed them better.
I loosely define a utility as any project designed to solve a singular and specific problem for a certain situation or business process.
For example, I built a small PHP application that accepts an export from an ecommerce store and parses the data into another format needed for a specific business process.
How could I design these better?
More from this author
I normally build a utility by having an idea of a problem to solve, and I jump right in to an editor and start typing.
Some time later, I find myself wanting to steal functionality from old utilities, but when I go to reuse some code, I find out how badly I programmed the thing! Generally I don't spend a lot of time on small utilities, so they are programmed without classes, namespaces, or even OOP. Procedural FTW!
It's made me think that I should be more organized, even in tiny projects.
Here are some issues I now consider before starting any new project.
1) The basics are required!
Regardless of how tiny the utility is, practice good programming! Use proper source formatting, naming conventions and commenting. Another developer should be able to see what's going on in the code with little effort.
Avoid procedural coding where possible.
I no longer allow myself to write sloppy code, even if the project is tiny or of limited use.
2) Define the project
It doesn't matter if the utility has a single function to perform: it should be well defined before coding begins. The definition of the app will include basic declarations, like who will use it, what data it will expect, and what output it's supposed to give.
Define data sources, security concerns, and whether the app will grow with more functions over time.
Where will the utility be hosted?
The more detailed the definition, the easier it is to pick tools and stay in scope while programming it. This is especially true if you're programming for someone else!
3) Will others work on it?
If other programmers will be involved, increase your documentation and commenting. Use source control, and focus on separation of concerns in your classes and methods.
If no programmer will ever need to read your code or work on it except you, keep to the basics and don't overwhelm yourself. Just make sure you can still make sense of it!
4) Source control?
Depending on the context of the utility—such as if it is an internal project for an organization that will own the work—the code may be hosted in a public repository. If so, increase documentation; add a
readme.md file; add DocBlocks to define ownership of the code, and use Semantic Versioning.
If there are concerns about intellectual rights and who owns the code, this would require you to throw a license in there.
5) Do I have to maintain it for the long haul?
If you foresee future development, assume that others will work on the app, and that it therefore needs source control, improved documentation, and a license attached.
You may not be the person to maintain future versions if the app is internal to an organization. It's better to spend the extra time on these chores than for future programmers to dismiss you as a poor programmer.
If you write well-documented code, you may be able to come back later for a letter of recommendation. (You can't take company-owned code with you, but at least you'll have a letter confirming all your work was good!)
6) Should I create an API, library, or neither?
It's beyond the scope of this article to define APIs and libraries, but it's still a significant decision to make, because it will change the entire methodology of your coding.
Will the tool be standalone, or will you distribute it as a library, or do you want to allow others to access the functionality through an API interface?
If you go the API route, you'll want robust handling of all inputs and outputs, data validation, data conversion, security, HTTP routing, endpoints and so on. Encryption and authentication become a concern too.
7) CMF, backend, configuration?
Does the utility itself require its own management interface, separate from the front-end context?
Do you need a back end as a means of providing access for an administrator to control the utility?
The biggest problem is that any content management framework (CMF) is likely to give you a lot of bloat and features you don't need just to run a little utility. But then again, the CMF is likely to give you its own API and helper tools, which may come in handy.
Alternatively, you can store all configuration information in a single file that only admins have access to.
In most cases, I just create a
config.php file and place all the config data in there and edit manually without an interface.
8) Package management?
Package management is the cool kid, but that doesn't mean we need to hang out and be friends!
It's easy to include a few libraries without using package management.
I have only found myself using it when I need more than two or three modules, or if those modules are complex.
If you choose to use Composer modules (for PHP), then I also suggest building your utility within the rules of Composer so that your project itself can be managed via Composer. Use the PSR-4 spec, folder names, and naming conventions for classes and so forth.
9) Front-end Framework?
A complex front end might arise where the user is meant to perform many steps, upload files, fill out forms, review data, visualize data, etc. As the front end becomes more complex, you may consider using a front-end framework.
By
frameworkI really just mean a CSS framework like Bootstrap, Foundation, or even something bigger that includes more visual modules and JavaScript widgets, such as jQuery or others.
I usually find myself writing all CSS from scratch, but if the project grows too big, I'll do a rewrite onFoundation perhaps.
10) Do I need logging?
Will you require any kind of historical record of the actions taken by the utility? Will you need an audit trail of who did what, when, from where, and for how long?
Again, if we're in a corporate environment and the utility is meant to be used by multiple people, a log may be necessary for tracking.
Good logging libraries are available in package managers, so if needed, that could be a reason to use package management.
11) Do I need hardened error handling?
Most of the time I create utilities with no thought for error handling. I tend to program with all errorsshown, and once everything works and there are no errors in my testing, I turn off showing errors at all.
You should think about whether you need complex error handling, front-end messages,
undofeatures, back-button management, autosave versus save button, popups and modal windows, and whether this will be tied in to a logging system.
Note that logging, auditing, error managing should be part of the early specifications. This should help you decide about using package management and frameworks right from the start.
12) Do I need extra security?
If your utility performs destructive data management or needs user authentication, then extra security is a no-brainer.
I tend to think, as soon as you need robust security, then use a framework with these features built in. You can use a framework with no management interface like Laravel, Kohana, Slim, Silex, and many others. Or use a framework with an interface like MODX, ProcessWire, or Bolt. Just make sure the framework has the features you need.
Reinventing the wheel is just not necessary. Don't write your own logging, security, user auth, database abstraction, etc. Just use a framework at that point.
13) Is it public-facing?
One big question to ask is whether the tool is only to be used internally, or if you'll allow access from the general web. If the former, is it still open internally to an organization where dozens or hundreds of people will have a crack at it?
You'll have to make sure your endpoints are well defined, and that you protect any auxiliary files and scripts as needed.
If you suspect high traffic, then you're talking caching mechanisms, especially where databases or highly dynamic data is generated. We're also talking security, logging, auth, and so on.
I would say, as a general rule, if you are creating a small utility to provide to the planet-at-large, use all common libraries, tools, methods, documentation, and even a framework.
Don't mess around when it comes to handing out public access: all bets are off, so just do everything by the books with modern, well-tested modules and frameworks!
Source (Site Point)
No comments:
Post a Comment