[Swan-dev] naming of functions that return something

[D. Hugh Redelmeier]

[Feel free to ignore this philosophical exploration.]

Algol distinguishes procedures and functions.  Let's use that terminology.

A procedure call is a kind of statement.  Statements are composed by 
sequential execution (left to right, top to bottom).  So it is natural to 
name something like this:

	convert_cat_to_dog(cat, dog);

or (we won't discuss which parameter order is best)

	convert_cat_to_dog(dog, cat);

A function call is composed in functional notation.  Reading 
inner-to-outer is right-to-left.  So this is more natural.

	felix = cat_from_dog(fido)

I'm claiming that htonl would be more natural as nfromhl.

I'm writing this to try to explore why I found the name 
same_chunk_as_in_pbs jarring.

  extern pb_stream same_chunk_as_in_pbs(chunk_t chunk, const char *name);

As I first read it, and even now, I read "as_in" as a unit (a chunk in 
psychological terms).  That made this a "garden path" name.  Oh, English.

I'm not sure what "same" is implying.  Perhaps that the in_pbs doesn't 
have its own copy of the memory.

I might have called this function
	in_pbs_for_chunk

I'm a little bit surprised by a pbs being returned from a function.  When 
I conceived of them, I didn't think of them as copyable.  Perhaps they 
were linked together.  But this turns out to be OK with the current 
implementation.