Entries Tagged 'Programming' ↓
June 26th, 2015 — Business and Clients, Programming
I have been freelancing as a remote developer for over ten years. I specialize in legacy systems and taking over abandoned and unfinished software projects. I see the problems customers have hiring and working with freelance developers. Here’s my advice for avoiding some of the potholes.
This article is about freelance software developers, programmers, and system administrators, because that’s where my experience is. Some of this applies to freelance designers, writers, marketing consultants, etc. I work through 10X Management, a talent agency for developers and technology professionals. I am available to consult with customers to help them find, hire, and manage freelance developers, and to define and prioritize requirements and measure progress.
Interviewing, hiring, and managing
I’m not going to get into step-by-step instructions regarding the nuts-and-bolts of finding, hiring, negotiating with, and paying freelancers, writing contracts, tax laws, etc. If you aren’t confident that you can evaluate and manage a freelance developer you should use an agency or hire a consultant who has that experience. Software development is expensive and takes time, managing programmers is hard.
Personality conflicts will kill your project and stress your team. Over and over I get involved in situations where the customer and the freelancer clashed personally. If you don’t feel comfortable with the freelancer when you interview them, find someone else. Be aware of your own rough edges and prejudices. Get someone else involved interviewing and managing freelancers. If you won’t be the main person working with the freelancer, get the people in your organization who will be involved in the selection and hiring, and pay attention to any objections they raise. Hiring someone without getting buy-in from the rest of your team gets everyone off on the wrong foot.
Many contract programming shops outsource most of their projects. Be sure you are talking to the people who will be working with you and your staff, not just an account executive or project manager who closes the deal but doesn’t do the work.
Be clear about your expectations, but back off any you can’t justify. For example you may feel strongly that you need someone working on site every day. That requirement will greatly reduce the pool of available freelancers. Is that an absolute requirement (for example, security clearance required, systems that can’t be accessed remotely, specialized hardware, etc.), or is it worry about not having control? Here are some things you should be clear about before you start interviewing freelancers:
- Your budget, total or for the first set of defined tasks.
- Your schedule.
- On-site time required? How much/how often?
- Who will the freelancer report to and work most closely with?
- Is a security clearance or background check required?
- Availability — how fast do you expect phone calls and emails returned? What qualifies as an emergency?
- Who owns the completed product?
- Do you have existing systems that are part of the project?
Before you start interviewing freelancers you need to have some high-level requirements defined. You should be specific without getting into unnecessary detail, and that takes some practice and editing. “Web developer needed for golf equipment retailer fulfilling 10,000+ orders per month, must interface with existing back-end system” is a lot better than “PHP and MySQL programmers with 3+ years experience.” Try to be detailed enough to attract people who will be a good match for your needs, but not so specific that you eliminate too many candidates. Avoid listing technical requirements (languages, tools, years of experience) unless they are absolutely necessary for the job, and you are able to evaluate the freelancer’s competence.
Check references and reputation
When you find a freelancer you like ask for examples of similar projects and references you can contact. Almost no one is going to put you in touch with their unhappy customers, but you should be able to get an idea of the freelancer’s history and reputation by talking to their previous customers and checking them out online.
A nice online portfolio, blog, customer testimonials, and a github profile are all things that a professional developer should have, but those are not sufficient to base a hiring decision on. Has the freelancer worked on projects of similar scale and scope? Online study assignments and side projects indicate enthusiasm but not necessarily professional skills or ability to deliver, so set your expectations (and payment) accordingly.
Business domain experience is at least as important as technical skills
Look for experience in your business domain, or a similar domain, and value that experience as much as checklists of technical skills. You probably are not qualified to determine how proficient someone is with PHP or Ruby. You can judge how much they know about your business domain, or a related domain. For example if you are looking for someone to work on an e-commerce site talk about inventory management, shipping charges, sales tax, payment processing, customer management. If the freelancer doesn’t understand your business or doesn’t ask questions about how it works your requirements aren’t going to make sense to them. Technical skills alone do not solve business problems.
I have sat in on many interviews where the customer and the developer talk past each other. The customer is trying to describe what they need in terms of business requirements, and the developer is talking about languages, tools, scaling, programming process. This disconnect starts at the beginning of the relationship and will, at best, lead to a false start or two, and at worst to a failed project. If you aren’t communicating with the freelancer or you don’t get the impression that they care about and understand your business needs, address that problem early on or find someone else.
Be alert to signs that the developer is going to use your project as an opportunity to try new programming languages or tools. Unless you want to be on the bleeding edge beta testing open source software insist that the developer use stable, mature tools that everyone else is using. It will be a lot easier for you to find people to work on software that is built with mainstream tools.
Define the tasks and deliverables
After personality fit, the biggest determinant of success or failure is how well you describe the tasks and deliverables. This is actually the hardest part of any software development project, so take some time to get it right. Get professional help if necessary. You need to break your project down into small well-defined tasks with clear deliverables. “Set up e-commerce site for my business” is not a specific requirement. What you want to end up with is a list of measurable tasks, in order, so the freelancer always knows what is next and you always know what has been completed. Every task should have an associated deliverable that clearly describes what “done” means for that task.
Defining requirements and setting priorities is one of the hard problems of software development. There are several techniques for managing requirements. Some people prefer the so-called waterfall or BDUF (big design up front) approach, others advocate agile techniques, where software is development in small steps so gaps in requirements can be discovered early without causing a lot of disruption. It’s important to recognize that most customers and most programmers are not very good at gathering and defining requirements, so be realistic. (It’s also important to recognize that no development process guarantees success.)
The best way to protect yourself from fights about missed and vague specifications and changing requirements during development is to start by describing the simplest possible thing that will work. Developers call this the minimum viable product, or MVP. You don’t have to define all your requirements in advance: you only need to define enough tasks to get started. With a list of small well-defined tasks and measurable deliverables you can quickly assess if the developer is working out as expected. You will discover misunderstandings and problems early on, and take action to get things on track or terminate the relationship. If you start with a big list of vague, incomplete requirements and let the developer work in isolation for months you won’t know for a long time if the project is is in the weeds, and the developer won’t know if they are not doing what you expect.
It’s hard to resist doing more than you originally planned when the programmer is telling you how easy it will be to add features, make your system into a platform with APIs, scale to Facebook-level traffic. Don’t go down the path of scope creep, it leads to unfinished projects. Insist that the developer do the simplest possible thing to meet requirements, and don’t let them expand requirements to account for things that aren’t likely to happen.
Communicate clearly and frequently, and don’t get caught up in process
Establish ground rules with the developer regarding communication, and be sure you follow those rules. If you expect the developer to answer phone calls and emails within an hour, you should do the same. I hear customers complain about developers who don’t respond to calls and emails for days or weeks. I also have experience with customers who don’t reply promptly, or at all, to questions I send, or who don’t deliver things they are responsible for on time. If you aren’t answering questions and giving the developer what they need your schedule will slip, and you will frustrate the developer. If you delegate day-to-day management or tasks like approving designs or producing graphics to someone else, make sure those things are getting done.
The developer may propose (or even demand) that you use their process and tools. If that makes sense to you, great. But be wary of developers who have a lot of process and make that your problem. As the customer you should be able to discuss requirements and report bugs in person, over the phone, or in an email — don’t agree to only communicate through online project management or bug reporting tools. Whatever process and tools the developer needs to use to deliver is their internal issue, it should not be forced on you, and you should not be paying for time spent on internal processes that don’t have a clear and measurable benefit to you.
You should agree with the developer that you need to have something working all the time. Don’t allow for weeks or months of development with no visible results — insist on small steps that build the system up bit by bit. Even if you start with a single web page that shows your logo and some mocked-up functionality, that’s better than having nothing to look at. You should also insist that the developer use source code control from the beginning (Subversion or git), that you have separate development, staging, and production environments, and that you are not using real customer information or credit card numbers for development or testing.
Pay for results, not fixed-fee or hourly
Another reason to work from a prioritized list of small tasks is payment. I’m astonished that customers and freelance developers agree to fixed-fee proposals with significant money and time at stake, and the entire project is described in one or two pages of exhibits tacked on to the contract. Unless you have a history with the freelancer that gives you confidence that they will deliver on time and on budget, or you are buying a mostly off-the-shelf solution with very little integration and customizing, a big fixed-fee contract is probably not a good idea. If you go into a project with a fixed-fee arrangement there’s a good chance you won’t know about schedule or cost overruns until late in the project, and there’s also a good chance you will be presented with costly change orders for every small change. Even experienced professional software project managers can’t anticipate all requirements or estimate tasks reliably. Don’t expect that you or the freelance developer will be the exception.
Paying a freelancer by the hour seems like a better plan when you don’t have experience working together. The problem with paying hourly is that deliverables become by-products. The focus on hours spent and time tracking can consume a lot of energy on both sides and lead to arguments about how much time something took or should have taken. I advise against paying hourly, but if you do pay hourly make sure you put a cap on the number of hours you will pay for.
Ideally you should pay for results: finished tasks and working deliverables. That only works if you defined your tasks and deliverables well enough so the freelancer can estimate the work, and you can determine if the estimate is reasonable. As I mentioned earlier, you don’t have to define the entire project in advance and break all of it down into small measurable tasks before you start; you can do that incrementally as the project proceeds. It’s easier for a web developer to estimate “Home page with our logo, main navigation menu, and content areas blocked out, no functionality” than “Start on e-commerce site, show progress in two weeks.” And it’s easier for you to see if the developer is getting the work done as expected and following instructions.
When I start working with a new customer I ask them to list their top five or ten problems, in order, most painful first. If the list is vague I work with the customer to make it more specific: “Web site slow” becomes “Searches with more than 100 results slow to display.” The goal is to have a list of problems we both understand, so I can work from the list, estimate the time I need to fix the problems, and the customer can determine if I’ve delivered.
I prefer to establish long-term relationships with customers and negotiate a retainer agreement, where the customer pays every month for a block of my time they can use for consulting, new development, enhancements, or maintenance. Once you have established a good working relationship and trust with a freelancer working out a retainer is a good way to insure they are available when you need them, and to keep your software development and maintenance costs predictable.
March 22nd, 2015 — Business and Clients, Programming, Web Development
MVC and web applications
MVC (model-view-controller) is a pattern or style of application design that dates back to 1970s and 80s. The idea is to enforce a separation of concerns, decoupling the user interface from the business logic and data persistence layer. MVC doesn’t require OOP (object-oriented programming), but in practice most MVC frameworks are implemented with classes and objects, because OOP can also support strict separation of concerns. There were MVC-style frameworks for PHP before Rails came along, but looking at the current popular PHP frameworks it’s obvious that Rails has inspired and influenced a lot of them.
MVC dates from the pre-web time of mainframes and dumb terminals, and long-running server processes that could update the user interface at any time. The web’s stateless request/response model meant giving up long-running server processes and dynamic interface updates. It’s common for Java- or .NET-based applications to maintain and coordinate state across requests and user sessions, and it’s now possible for the server to push updates to the client (web browser). That’s not how PHP works, though.
So-called MVC frameworks for web applications generally aren’t strictly MVC. Instead they use a router-handler-template-model style that superficially looks like MVC, but doesn’t have some of the important features of MVC. For example web framework “models” are usually dumb layers over a database to do CRUD (create, read, update, delete) operations. Business logic that probably belongs in the model is usually pushed into the controller, and models usually don’t notify the controller or view when something changes in the model. That doesn’t fit the CRUD paradigm or how request/response PHP applications work.
If you look at PHP MVC frameworks what you find are big class libraries that implement some flavor of MVC. The class libraries don’t model a business domain, so the business logic is forced into the framework’s structure, rather than the framework supporting the business logic. Trying to figure out where the business logic should go—controller? model? view?—is a big source of confusion, with no clear right answer. If the main advantage of using a framework is starting with a structure to hang the business logic on, why is it so hard to figure out where that business logic should go?
My experience with PHP frameworks
I’ve used several PHP frameworks in my own projects, and encountered them in code that I’ve taken on for maintenance and enhancement. I’ve written my own PHP framework that is deployed in a couple of real web applications. In every application I’ve run into the same thing: business logic scattered around at all levels, and difficulty figuring out exactly where something happens. Separation of concerns shouldn’t mean fragmentation of concerns, but that’s often what happens.
Another real example: I inherited a web app that displayed a single page of Instagram and Twitter posts matching a handful of hashtags and authors. The previous developer (whom my client had fired after the application was delivered very late and buggy) had chosen to use the Zend Framework 2 for what seems like a fairly simple task. The code was classic OOP ravioli code: many classes with methods doing very granular operations. It was hard to figure out where anything happened because the overall control flow was not apparent, and state was scattered among many objects that had implicit relationships. All of this was wedged into ZF2 for no clear reason. This was tens of thousands of lines of opaque code that didn’t work. I replaced it with a lighter-weight page that just did what it was supposed to do: call the Instagram and Twitter APIs, provide some simple caching, and generate a page of posts. Adding authors or updating the hashtag list turned into simple one-line changes in a config file. The result was less than 1,000 lines, including comments.
This doesn’t mean that every application based on a PHP framework is poorly written or hard to maintain. It means that I’ve worked on a lot of framework-based applications and I’ve seen the same problems again and again.
Is everyone doing it wrong?
Before I started working on web applications I spent over ten years developing and working on OOP enterprise and educational applications, mostly in C++. When these projects went into the weeds or failed, or turned out to be very hard to maintain and extend, the programmers would always blame it on a poorly-designed class structure. If we (or the original developers) could just model the domain correctly in classes and objects everything would be great. The OOP paradigm was never doubted; it’s just that most programmers apparently are too inexperienced or lazy to do it right.
Read the threads online where someone asks how to implement something “correctly” in their PHP framework. If you put any business logic in the template (or view) you are doing it wrong. If you emit HTML from the controller you are doing it wrong. If the model “knows” about user interactions you are doing it wrong. Do business rules that affect presentation, like shipping options based on order total and destination, go in the presentation layer? Do external services like credit card processing or calculating shipping charges go into the model or into the controller? How do I know when I’m doing it wrong when there’s no agreement on how to do it right?
Programming is subject to fashion and religion, based on opinion, faith, and fear of looking stupid or inexperienced. Pick a programming topic and you can read all day about the right way to do it, or a criticism of a supposedly wrong way. These arguments seldom have any foundation based on facts or studies—they are anecdotal and biased. Programmers can be just as certain that their favorite approach is the one right way as they are about spaces versus tabs in source code, with exactly the same facts to base their arguments on: none. The only time I take the right way/wrong way discussions seriously is when they are about algorithms or relational databases, because there’s an actual theoretical and mathematical foundation to base opinions on.
My return to the “mullet style”
Recently I took on a ground-up development project, something I rarely do. Originally it was a debugging job, but the WordPress-based application was such a mess that I had to tell my client they’d be better off starting over, and I don’t tell clients that very often. I decided to revisit my simple MVC framework and improve it with the latest PHP features. I had a single entry to the application to handle global configuration, class autoloader, security, session management, and request routing. I had models that did actual business logic operations on the database (not just CRUD). I had controllers that would process inputs, update the models, and set up variables for the templates. And I had templates that could only contain simple PHP if/then/else and loops. Referring to models or knowing about business rules implemented elsewhere was not allowed. I tried hard to work within the framework and the rules I had made for myself. I refactored the framework two or three times to implement pure solutions to problems I ran into. I had over 7,000 lines of PHP code, a lot of it framework boilerplate and moving data around to enforce separation. It worked, but I was unhappy with it.
I looked at other frameworks, assuming I was doing it wrong, but my architecture was very close to the other leading frameworks. I got some good ideas but never shook the feeling that I was trying too hard to force the application into the framework, and spending a lot of time enforcing what I thought was the right way (or at least not the very wrong way that would invite abuse on StackOverflow and github).
What finally pushed me to abandon the framework approach was realizing that I was flipping through too many files to follow the flow of control, and that too much of my code was there only to comply with the framework’s separation of concerns. Having business logic scattered around in multiple files and classes is painful because I work on a 13″ laptop with vim. Maybe MVC frameworks are easier to work with on multiple 23″ screens, but on a small screen the buffer changes and screen splits cause too many mental context switches. I wanted to see everything that was happening on a single page, so I could keep it in my head and think through it.
Of course this is all just my opinion, based on my own experience, biases, and work style. If PHP MVC works for you, great, but you may be surprised to find it’s not as robust or maintainable as you think it is. There’s still no silver bullet when it comes to software development.
Postscript: Don’t throw the baby out with the bath water
I’m not advocating writing spaghetti code or ignoring good programming techniques. It’s possible to write good or bad PHP code whether you use a framework or not. Keep in mind that the popular frameworks do some useful things for you that you will have to do yourself if you don’t use a framework. You have to protect your application from common attacks: SQL injection, XSS (cross-site scripting), CSRF (cross-site request forgery), session hijacking, cookie tampering, insecure API endpoints and AJAX functions, etc. Learn about these attacks and use PHP’s built-in functions or a library you trust to protect your application. Treat all inputs as suspect, whether they come from an HTTP request, a cookie, a database query, or an external service. Use a database library such as PDO, never interpolate variables into a SQL statement. Sanitize everything that is output as HTML or JSON. Make sure your web server blocks attempts to access git or svn repositories, or anything else in your document root that shouldn’t be accessed. Build in error reporting and logging from the beginning. Don’t use global variables. Keep it clean and simple, err on the side of caution.
March 1st, 2015 — Business and Clients, Programming, Web Development
Here’s a list of things I know, or at least know about, as a web developer. I’m sure I’ve left a lot of things out. Web development is a large and complex collection of technologies, tools, languages, protocols, and services. I started programming for the web back in 1995, so I’ve been able to adapt to changes and learn new tools as they were released. If I had to learn web development from scratch today I’m sure it would take me a long time to master even a few of these things.
If you are doing a new project from scratch you’ll get to pick and choose your tools and “stack.” If you are coming into a team that has already made these decisions you’ll have to adapt. If you work with legacy code you’ll have to get familiar with more languages, frameworks, libraries, technologies, and programming styles.
Web applications usually have two big pieces: the front-end code that runs in the browser, and the back-end code that runs on the server.
The front end (browser side)
You’ll need to know HTML, in detail. HTML5 is the latest but you’ll probably have to know how it’s different from HTML4. You also need to know how styles work: CSS, the box model, inline styles, inheritance, specificity, resets, the differences across browsers and browser versions. You will probably need to know about grid systems, and responsive layouts. Most likely you’ll need to learn one or more of the popular front-end frameworks: Bootstrap, Foundation, Toast, Yaml, etc. You may have to know about CSS preprocessors, like Less and Sass.
If you’re lucky you have some design skills, or you are working with a designer who understands the web. Otherwise you’ll be responsible for layout, typography, colors, image formats and optimization, for a start. Customers often don’t understand that a web page is not a Photoshop proof, that they can’t put a 40MB TIFF file on their home page, or why their favorite font is not available to everyone else.
You probably have to know something about the different kinds of devices people use to browse the web and how that affects design and front-end implementation. Desktop and laptop computers, tablets, and phones have obvious and subtle differences. There’s no hovering on most touchscreen devices, for example. High-resolution Retina or 4K displays may give you grief. Mobile users often have slow connections and data rate caps and limits, so you need to think about that and test on all kinds of devices, with wi-fi and cellular connections.
Somewhere along the way you need to understand the HTTP protocol, at least what request/response and statelessness means. You need to understand cookies, browser caching, expiration, content types and MIME. You have to know about mixing content retrieved with HTTP and HTTPS. You will probably need to understand synchronous vs. asynchronous requests.
The back end (server side)
Almost all web applications use a database or some kind of datastore accessible by the web server. MySQL, MS SQL Server, PostgreSQL, SQLite, Oracle, DB/2 are all relational database management systems (RDBMSs) that use the relational model and some dialect of the SQL language. You may use a non-relational (so-called NoSQL) database, and there are many of those: MongoDB, CouchDB, Cassandra, Redis, Memcached. Many web applications use more than one database or data storage tool. The database management stuff may be partially hidden behind an ORM provided by your application framework, but it’s likely you will eventually have to understand the details of how your data is stored and retrieved, how data integrity is assured, and how the data is backed up and secured.
External services give you access to all kinds of things: sending and receiving email, credit card and check payment processing, analytics, maps and location services — the list is endless. If your web application uses external services you will have to learn about APIs, REST, authentication, JSON, XML, RPC, SOAP. You may have to use or write a scraper or crawler that extracts data from sites that don’t offer an API. You’ll probably have to work with curl/libcurl at some point when getting your server to talk to an external service.
Besides the languages there are programming techniques, styles, and workflows you will have to understand: object-oriented programming (OOP), maybe functional programming, certainly imperative programming, test-driven development (TDD), Agile, SCRUM, etc. You may need to use a debugger for the server-side code.
The web server has to be hosted somewhere. It may be a server in the office, or co-located at a hosting facility. More likely it will be a shared, dedicated, or managed cloud instance at Amazon, Rackspace, Google, Microsoft, or any number of cloud hosting providers. Hosting decisions can limit your choice of languages and tools, how much control you have over the server configuration, and things like email handling, DNS, bandwidth limits, and so on.
Security and legal/regulatory issues
As soon as your application goes live on the public internet it will be attacked by bots and hackers. You have to understand common vulnerabilities like SQL injection, cross-site scripting (XSS), cross-site request forgery (CSRF), cross-domain request issues, CORS, session hijacking, spambots. If your employer or customer doesn’t have a system administrator you will have to know about firewalls, keypair authentication, and securing your servers. You have to keep up with security threats and patches to the server operating system and every part of your stack.
If you accept credit cards or electronic payments on your site you will be subject to PCI compliance audits. Other types of personal data you collect and store may be subject to other compliance and audit rules (HIPAA, COPPA). Every country your site does business in will have its own legal and regulatory requirements.
You will need to master at least one text editor. You will have to know how to get your code uploaded to a server with FTP, SCP, or some other deployment tool. You should be using source code version control: git, subversion, Mercurial. Eventually you will have to learn your way around UNIX, the file system, the shell, tools like find, grep, vim, emacs, nano, ssh, cron.
You will have to understand domain name registration, DNS, probably SSL certificates. You will probably want to monitor your server for crashes and outages and spikes in activity than can signal a denial of service attack or something else wrong.
All of the languages, libraries, frameworks, and tools you choose will be updated and patched frequently, so you have to stay on top of that while making sure updates don’t break your application. Even moderately-complex web applications can have tens or hundreds of dependencies at different layers in the stack. Dependency management and managing versions and updates can turn into a risky and complicated problem all on its own, and of course there are tools to learn for that.
A large number of web sites are based on content-management systems: WordPress, Drupal, etc. You may have to know the advantages and shortcomings of those platforms, along with a lot of the stuff listed above.
If your application get significant traffic and users you will need to think about bandwidth (especially costs), performance, scaling. Decisions that made sense during development or with little traffic can come back to plague you when your site gets loaded.