How to explain method calls? - function

let's consider a small method:
int MyFunction(string foo, int bar)
{
...
}
and some calls:
MyFunction("",0)
int x = MyFunction(foo1,bar1)
How would you explain this to a non-technical persons? Has anybody a nice metaphor?
I tried to explain method calling (or function application) several times, but I failed. Seems I can't find the right words here.
Regards,
forki
UPDATE: It is important for me to explain how the parameters are passed / matched.

(Highly non-technical solution)
It's like making an order:
Calling the method = dialing the right number
Passing the arguments = giving your details
the method does is job
Getting a return value = getting what you ordered

You could tell function is a process available into an object that could be called by other. Lets say "You" is an object with function "Work". Your "Boss" is the caller object. Your Boss then can call you to Work with different type (which is parameter).
In the end Your "Boss" can ask "You" to Work("encode this") or Work("check email") or Work("finish deadline"), etc.

How about delegating a task? Imagine you’re baking a cake and ran out of flour. Instead of buying some yourself you could just send your kid with instructions to buy flour. Input: money, output: flour.

It's difficult to understand the "method call" concept if you don't understand first the
flow of control.
A simple explanation is that methods, or routines, is a construct for packeting instructions
in order to reuse them and make the code more readable.
Calling a method, temporarily, switches the execution flow to that method.

C:: do(a ,b)
You are telling C to do something , given the condition a and b.

The best approach is probably to come up with a domain specific example which the person you are explaining to can relate to. If she is working with the post office, you should describe the function "send letter with this text to this recipient", where recipient is a parameter (containing the address) and message is the parameter for the textual content.
Parameter order is not important as long as you have a name for each parameter. Trying to explain why order is important in some arcane programming language is fruitless.

How about
Calling a function: Ask the software to perform xxx task
Returning value type function: Ask your software to perform xxx task and tell you the outcome of the operation
Calling a function with param: Given X is this value and Y is thisvalue, ask your software to perform xxx task (and tell you the outcome of the operation)

Think of the system as a teller at a desk. To call a function you fill in a form to ask the system to do something, hand it to the teller. They go off and do the work, then hand you back a piece of paper with the result written on it. Depending on what you want the system to do, you pick an appropriate form.
The form for MyMethod says:
MYMETHOD REQUISITION FORM:
String _______
int _______
This analogy can be extended in all kinds of ways. Wouldn't it be handy if the form told you what the purpose of the String and int were? That's where languages with named parameters come in.
For OO, instead of having one desk for the whole system, each object is its own teller, you hand a form to them, and in order to get the job done, they hand a lot more forms back and forth between each other. Etc.

Related

Why is a function call called a "function call"?

I know what a function call is. I know what it does. I've debugged it a lot. I do have some intuitive sense on why it makes sense to use the term "function call", but when it comes down to it, I can't explain this properly like I could with a return statement.
For example, with a return statement the answer is: it's called a "return" because you return to where you came from. You return to the line from where the function was called. So it makes sense why the end of a function (implicitly or explicitly) returns.
I've noticed that for people who speak English as their native language this easier to grasp (especially with more obscure words such as "cache"). However, for people like me (Dutch, learned English through videogames and subtitled television), it's harder to grasp.
I googled for this question, but I get all kinds of entries what a function call is and how it works. I associate the word "call" a lot with telephones, since that's what I use it mainly for in English.
I asked a similar question on what the "de-" means in the word "dereference" here: What does the de- prefix in dereference mean? Is there a linguistic explanation for it?
The term call has a wide meaning. When used in calling a function, you would probably best interpret that as short for calling a function for execution. See the following meaning given by the Free Dictionary:
To order or request to undertake a particular activity or work; summon:
She was called for jury duty. He was called to the priesthood.
This is very close in meaning to another expression used for invoking functions: call upon a function.
That should make sense in the context of functions. The function provides a service, and it is called upon to provide it now. In both cases the meaning is: request the code in a function to be executed.
NB: In Dutch you may translate with oproepen or (less common) aanroepen.
Thanks to #hvj I noticed that the comments of the really related -- though not the same! Since I want to know it linguistically not historically -- question referenced a paper that was behind a paywall ( see http://dl.acm.org/citation.cfm?id=609816&CFID=888670230&CFTOKEN=46456506 ). I read the paper and then I found this small piece:
In this type of routine it is arranged that a sequence of operations is performed each time the subroutine is called into action.
So apparently the Zeitgeist of that time was phrasing it as calling sub-routines into action. Side note: they also talked about returning control from a sub-routine to the main program.

When is passing a subprogram as a parameter necessary

I've been reading a Concepts of Programming Languages by Robert W. Sebesta and in chapter 9 there is a brief section on passing a SubProgram to a function as a parameter. The section on this is extremely brief, about 1.5 pages, and the only explanation to its application is:
When a subprogram must sample some mathematical function. Such as a Subprogram that does numerical integration by estimating the area under a graph of a function by sampling the function at a number of different points. Such a Subprogram should be usable everywhere.
This is completely off from anything I have ever learned. If I were to approach this problem in my own way I would create a function object and create a function that accomplishes the above and accepts function objects.
I have no clue why this is a design issue for languages because I have no idea where I would ever use this. A quick search hasn't made this any clearer for me.
Apparently you can accomplish this in C and C++ by utilizing pointers. Languages that allow nested Subprograms such as JavaScript allow you do do this in 3 separate ways:
function sub1() {
var x;
function sub2() {
alert( x ); //Creates a dialog box with the value of x
};
function sub3() {
var x;
x = 3;
sub4( sub2 ); //*shallow binding* the environment of the
//call statement that enacts the passed
//subprogram
};
function sub4( subx ) {
var x;
x = 4;
subx();
};
x=1;
sub3();
};
I'd appreciate any insight offered.
Being able to pass "methods" is very useful for a variety of reasons. Among them:
Code which is performing a complicated operation might wish to provide a means of either notifying a user of its progress or allowing the user to cancel it. Having the code for the complicated operation has to do those actions itself will both add complexity to it and also cause ugliness if it's invoked from code which uses a different style of progress bar or "Cancel" button. By contrast, having the caller supply an UpdateStatusAndCheckCancel() method means that the caller can supply a method which will update whatever style of progress bar and cancellation method the caller wants to use.
Being able to store methods within a table can greatly simplify code that needs to export objects to a file and later import them again. Rather than needing to have code say
if (ObjectType == "Square")
AddObject(new Square(ObjectParams));
else if (ObjectType == "Circle")
AddObject(new Circle(ObjectParams));`
etc. for every kind of object
code can say something like
if (ObjectCreators.TryGetValue(ObjectType, out factory))
AddObject(factory(ObjectParams));
to handle all kinds of object whose creation methods have been added to ObjectCreators.
Sometimes it's desirable to be able to handle events that may occur at some unknown time in the future; the author of code which knows when those events occur might have no clue about what things are supposed to happen then. Allowing the person who wants the action to happen to give a method to the code which will know when it happens allows for that code to perform the action at the right time without having to know what it should do.
The first situation represents a special case of callback where the function which is given the method is expected to only use it before it returns. The second situation is an example of what's sometimes referred to as a "factory pattern" or "dependency injection" [though those terms are useful in some broader contexts as well]. The third case is commonly handled using constructs which frameworks refer to as events, or else with an "observer" pattern [the observer asks the observable object to notify it when something happens].

Question about grouping or separating functions / methods that are alike

I'll take a real example I have to implement in a program I'm coding:
I have a database that has the score of every game bowled in the past three years in a bowling center. With a GUI, you can choose to either search for the best score on each lane, search for the best score between two dates, for the best score for each week, etc.
I'm wondering what the best way to implement this is. Should I code something like this:
public Vector<Scores> grabMaxScores(sortType, param1, param2)
{
if(sortType.equals("By lane"))
...
else if(sortType.equals("Between given dates")
...
}
Or is it more appropriate to code different methods for each type and call the correct one in the listener?
public Vector<Scores> grabMaxScoresBetweenDates(startDate, endDate)
{
...
}
public Vector<Scores> grabMaxScoresByLane(minLane, maxLane)
{
...
}
I'm not necessarily asking for this particular problem, it's just a question I find asking myself often when I'm coding multiple methods that are alike where the principle is the same, but the parameters are different.
I can see there are good reasons to use each of them, but I want to know if there is a "more correct" or standard way of coding this.
In my personal opinion, I would prefer your second option over the first. This is because you have the opportunity to be precise about things like the types of the parameters. For example, minLane and maxLane may just be integers, but startDate and endDate could very well be Date objects. It's often nicer if you can actually specify what you expect, as it reduces the need for such things as casting and range checks, etc. Also, I would find it more readable, as the function names just say what you are trying to do.
However, I may have an alternative idea, which is kind of a variation on your first example (I actually got this inspiration from Java's Comparator, in case you're familiar with that). Rather than pass a string as the first argument, pass some sort of Selector object. Selector would be the name of a class or a interface, which would look something like so (in Java):
interface Selector {
public void select(Score next);
public Score getBest( );
}
If the select method "likes" the value of next which is given to it, it can store the value for later. If it doesn't like it, it can simply discard it, and keep whatever value it already has. After all the data is processed, the best value will be left over, and can be requested by calling getBest. Of course, you can alter the interface to suit your particular needs (e.g. it seems like you might be expecting more than one value to be retrieved. Also, generics might help a lot as well).
The reason I like this idea is that now your function is very general purpose. In order to add new functionality, you don't need to add functions, and you don't need to modify any functions you already have. Instead, the user of your code can simply define their own implementation of Selector as they see fit. This allows your code to be far more compositional, which makes it easier to use. The only inconvenience is the need to define implementations of Selector, though, you could also provide several default ones.
The approach you have used would also work. But if you want to add some new functionality like "get lowest scores on Friday evening", you will need to add one more function, which kinda not so good thing to do.
As you have already have the data in a database you can generate database queries which would fetch the required results and display. So you need not modify your code every time.

Advantages of passing a function as a parameter

Just studying for an exam and I can't find the answer to this question in our notes. Any help would be great.
Many languages permit subroutines/functions to be passed as
parameters. List two advantages provided by this, and motivate each
advantage with a clear explanatory example (this need not be code of
pseudo-code).
Think you are a manager of a charming singer ( in computer life : a program) , in the following two ways to start your morning.
Situation 1: You have to tell some underling to do the following a) get breakfast for the star and take great care with the kind of croissants she likes, remember she is very upset when she wakes up etc.. b) Put all cables on the stages using such and such power this lights but not that one , these colors ...
Situation 2: Ask your underling: Ask the majordomo to give our star her usual breakfast. Then ask the crew to take care of the stage for the usual songs.
Situation One is wrong from a computer point of view, it is typical of a quick and dirty way of doing. Yes you have the guy at hand but he is doing all the errands and handling several responsibilities of different types so he may be confused and moreover the order is long and detailed.
In situation two you are delegating, this handles the complexity , the order are short, we know who is doing the which jobs so we won't find a pink huge light bulb in the tea cup of the star (you think it is a joke but that is exactly what a bug is) .
In a few words complexity is partitioned in a meaningful way.
If you do not see why situation two is like calling functions here is a pseudo code.
extern FUNCTION majordomo( client , service , options ) ;
extern FUNCTION crew ( task , options ) ;
FUNCTION startMorning() BEGIN
call ( underling, majordomo( for_ourstar, usual_breakfast, she_is_picky));
call ( underling, crew(usual cables, bright lights));
END
The primary advantage is that if the function being called calls another function, you can modify the behavior of the function being called by specifying which other function is called.
Sorry, beyond that, you'll need to do your own homework.
One of the things passing an 'action' function to a method brings is the ability to perform an action against a collection without exposing the internals of that collection.
A typical use is, iterating over a private collection calling the passed function on each item.
Another is as a callback method.
I simple answer would be the function passed might get used as a callback function.
When the function completes it's job, it would call the callback function with or w/o arguments.
Applying a certain action to all members of a collection. (ie. square every number in it).
Consider a function that sorts an array of objects based on comparison sorting. Such a function needs a way to compare 2 objects and tell which is greater than the other. You can pass such a general sort function a pointer to the array and a pointer to the function that helps it compare any 2 objects.
See STL's sort for an example.

api documentation and "value limits": do they match?

Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ?
Note: I am not talking about comments within the code
By "value limits", I mean:
does a parameter can support a null value (or an empty String, or...) ?
does a 'return value' can be null or is guaranteed to never be null (or can be "empty", or...) ?
Sample:
What I often see (without having access to source code) is:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* #param aReaderNameRegexp filter in order to return only reader matching the regexp
* #return array of reader names
*/
String[] getReaderNames(final String aReaderNameRegexp);
What I like to see would be:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* #param aReaderNameRegexp filter in order to return only reader matching the regexp
* (can be null or empty)
* #return array of reader names
* (null if Report has not yet been published,
* empty array if no reader match criteria,
* reader names array matching regexp, or all readers if regexp is null or empty)
*/
String[] getReaderNames(final String aReaderNameRegexp);
My point is:
When I use a library with a getReaderNames() function in it, I often do not even need to read the API documentation to guess what it does. But I need to be sure how to use it.
My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...
Edit:
This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?
I think they can belong together but don't necessarily have to belong together. In your scenario, it seems like it makes sense that the limits are documented in such a way that they appear in the generated API documentation and intellisense (if the language/IDE support it).
I think it does depend on the language as well. For example, Ada has a native data type that is a "restricted integer", where you define an integer variable and explicitly indicate that it will only (and always) be within a certain numeric range. In that case, the datatype itself indicates the restriction. It should still be visible and discoverable through the API documentation and intellisense, but wouldn't be something that a developer has to specify in the comments.
However, languages like Java and C# don't have this type of restricted integer, so the developer would have to specify it in the comments if it were information that should become part of the public documentation.
I think those kinds of boundary conditions most definitely belong in the API. However, I would (and often do) go a step further and indicate WHAT those null values mean. Either I indicate it will throw an exception, or I explain what the expected results are when the boundary value is passed in.
It's hard to remember to always do this, but it's a good thing for users of your class. It's also difficult to maintain it if the contract the method presents changes (like null values are changed to no be allowed)... you have to be diligent also to update the docs when you change the semantics of the method.
Question 1
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation?
Almost never.
Question 2
My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...
If I used a function not properly I would expect a RuntimeException thrown by the method or a RuntimeException in another (sometimes very far) part of the program.
Comments like #param aReaderNameRegexp filter in order to ... (can be null or empty) seems to me a way to implement Design by Contract in a human-being language inside Javadoc.
Using Javadoc to enforce Design by Contract was used by iContract, now resurrected into JcontractS, that let you specify invariants, preconditions, postconditions, in more formalized way compared to the human-being language.
Question 3
This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?
Java language doesn't have a Design by Contract feature, so you might be tempted to use Execption but I agree with you about the fact that you have to be aware about When to choose checked and unchecked exceptions. Probably you might use unchecked IllegalArgumentException, IllegalStateException, or you might use unit testing, but the major problem is how to communicate to other programmers that such code is about Design By Contract and should be considered as a contract before changing it too lightly.
I think they do, and have always placed comments in the header files (c++) arcordingly.
In addition to valid input/output/return comments, I also note which exceptions are likly to be thrown by the function (since I often want to use the return value for...well returning a value, I prefer exceptions over error codes)
//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);
#Fire Lancer: Right! I forgot about exception, but I would like to see them mentioned, especially the unchecked 'runtime' exception that this public method could throw
#Mike Stone:
you have to be diligent also to update the docs when you change the semantics of the method.
Mmmm I sure hope that the public API documentation is at the very least updated whenever a change -- that affects the contract of the function -- takes place. If not, those API documentations could be drop altogether.
To add food to yours thoughts (and go with #Scott Dorman), I just stumble upon the future of java7 annotations
What does that means ? That certain 'boundary conditions', rather than being in the documentation, should be better off in the API itself, and automatically used, at compilation time, with appropriate 'assert' generated code.
That way, if a '#CheckForNull' is in the API, the writer of the function might get away with not even documenting it! And if the semantic change, its API will reflect that change (like 'no more #CheckForNull' for instance)
That kind of approach suggests that documentation, for 'boundary conditions', is an extra bonus rather than a mandatory practice.
However, that does not cover the special values of the return object of a function. For that, a complete documentation is still needed.