Establish convention for function naming and enforce it

[lhstrh]

What is our convention for selecting the name for a function that "does something" between the following:

1. do_something
2. lf_do_something
3. _lf_do_something

Good question. I think the original intent was that do_something should only be used for static functions, where the scope is limited to the file. lf_do_something should be used for user-facing functions, such as those used in reaction bodies. And _lf_do_something should be used for things that can't be static because they are used in multiple files, but they are functions that a user would never invoke.

The problem I ran into is that it's not always clear which functions a user might want to invoke, and this could change over time. For example, should it be lf_new_reactor or _lf_new_reactor? lf_allocate or _lf_allocate?

I've been opting for doing away with the leading underscore when there is any doubt, but I wonder whether we should do away with it completely? Whether something is user facing, I think, should be determined by which header file declares it. If it's declared in reactor.h, then it is user facing and is in scope for reactions. If it is declared in reactor_common.h, then it is not in scope for reactions. If we organize the Doxygen docs well, all of this could be made very clear.

An advantage of doing away with the underscores altogether is that we can change our minds later relatively easily. Right now, _lf_schedule_at_tag is not a user-facing function, but maybe we will want it to be later. If we remove the leading underscore now, then the change is painless: Just move its declaration to reactor.h.

So my proposal is:

1. do_something for static functions (scope limited to the current file).
2. lf_do_something for everything else.

This PR does not make this change, but maybe we can do is part of the formatting PR? Or as a separate PR in rapid succession?

Edward

Originally posted by @edwardalee in #354 (comment)

[petervdonovan]

This seems like the sort of thing that can be automated, much like formatting. If we choose to care about such things then it would be nice if at least we do not have to expect human beings to care about them when they are doing manual code review.