When you start to define a service, think about the consumer of your service and what their skill levels are; are they experienced developers, are they new to the framework, or are they in-between? Does your service require knowledge of higher-level concepts to comprehend? Or, is it very basic to comprehend? These are all things you should think about, because the harder it is for the developer to consume your service, the more painful their day-to-day life will be when using it. If you make your service easy to consume, developers will thank you for making things easy for them.

Use verb-noun combinations for method names, don't use abbreviations or contractions, and don't use acronyms unless widely accepted. If only every service and framework developer followed this practice, our lives would be easier. I find it hard to figure out what someone was thinking when I see method names such as repr() or strstr(); they're not English words, they're not familiar acronyms, and you can't tell what they do just by looking at them. Using verb-noun combinations and favoring readability, method names such as uploadFile, calculateSRMColor, and startMashTimer all help the developer to understand your service's interface. The developer may not know what a Standard Reference Method (SRM) color is, but they can pretty much figure out it is an acronym that has to do with the business domain and that if they call it they are going to have the service calculate it for them.

When designing your service interface, you should use the single-responsibility principle and limit your service's functionality based on its intended use. If the service is designed to calculate recipe parameters, limit it to just those methods; put other methods that do not deal with calculating recipe parameters into a different service. Sure, the number of services you'll end up with will be higher; however, each service will be easier to maintain since the amount of code it contains will be smaller and all in one place. Your services will also be easier to test, since you will be able to isolate their code easily. We'll cover this in depth later in this chapter when we talk about service testability.

Keep consistency across all of your method names to make your service interface easier to consume. If each of your services uses different naming methods, the developer trying to consume your service is going to loath your existence for all eternity. If one method that retrieves fermentable ingredients for a recipe is called getFermentableIngredients and another method that retrieves miscellaneous ingredients for a recipe is called retrieveMiscelaneousIngredients, how is the developer to know that they both go out to the server and return data? Does the method that begins with get only return data from the service and not request the data from the server? Is there another method he/she needs to call first to retrieve the data from the server? By keeping method names consistent in your service definitions, you can eliminate this confusion.

Keep the interface simple by planning for the top usage scenarios of each service. In other words, don't include service functionality that isn't going to be used. Let's say you're building a data service and there is some data that is read-only; do you need to add create, update, and delete methods for that data? If the methods will never be called, don't add them to your service. Use the agile development principle of never adding code before it's time and when there comes a time, add it to your service.

Each method should do one and only one thing. Break out functionality into separate methods and avoid using SWITCH statements to execute functionality based on function parameters. These types of methods only lead to testing nightmares, they will be the source of bugs and should be avoided at all costs. It hurts nothing to add a method for each specialized case and it'll make your service much easier to test. If there is a lot of redundant code once you're done, look at refactoring your code or using libraries such as underscore or lodash to leverage functional programming paradigms to implement the functionality.

Document your service interface using JSDoc, YUIDoc, Ext Doc, or some other tool to provide consumers a productivity boost. Many popular Integrated Development Environments (IDEs) can parse JSDoc-formatted comments in your code and provide IntelliSense prompts to the developer as they are editing their code.

These prompts help developers to understand how to call your service, what parameters need to be passed into a method, and what type the parameters need to be. These prompts make consuming a service much easier and help developers avoid having to keep looking at documentation while they are coding.

Now that we've covered some core guidelines to use when designing your service, let's take a look at how you should design your service for testability.