Suppose you have a team working on a project. You need to coordinate their work. You want them to able to work on different things at the same time, and have their code run when you bring all the parts together.
Functions and function libraries help that happen. For example, say Adela and Ethan were working on this version of the sales tax app. They want to be able to work at the same time. But how can they do that?
One way is for Ethan to work on the main page, and Adela to work on the library of validation functions. They're working on different files, so they can work at the same time.
Adela
But how can we be sure that our code will work when the pieces are put together?
Let's check out some of the code Ethan might write:
- // Check the state.
- $stateShortName = getParamFromGet('state');
- $stateErrorMessage = checkState($stateShortName);
- // Check the price.
- $price = getParamFromGet('price');
- $priceErrorMessage = checkPrice($price);
Take line 14. If Adela writes a function called checkState() that takes one param, and returns an error message, it should fit with Ethan's program.
The name, params, and return of a function are called the function's signature.
Where is a function's signature documented?
Ray
Oh! My dude! In those comments at the top of the function!
Right! In the PHPDocs.
- /**
- * Check the state.
- * @param mixed $state State from user.
- * @return string Error message, MT if OK.
- */
- function checkState($state) {
This documentation is kind of a contract. It says what the function will do, based on what data it gets.
It's also called a specification, or spec.
What should Adela and Ethan do before they start writing code, to make sure their work will fit together?
Georgina
Well, if I was them, I'd write the signatures for the functions. Then they can work independently.
Good idea!
That doesn't mean the specs can't change. It's common to have to go back and add some functions, change params, etc. But having the specs decided is a Big Win.
Job interview
This sounds good in a job interview: "I learned how to help development teams coordinate their work."