NOTE: Most of the naming examples used in this Wiki page no longer exist.  They have been converted to the naming conventions described in this Wiki page.  While they are good examples, they no longer reflect the current state of the code base.

Legacy smooshed-together names

There has been some controvery lately about the consistency of naming of OS internal functions. We should come to a consensus on the desired naming of conventions for internal OS functions before we start arbitrarily changing names.

NuttX function names are all lower case. That is required by the naming standard. Historically, has used a subsystem name, an underscore, then all of the renaming words smooshed together. For example.

void sched_mergeprioritized(FAR dq_queue_t *list1, FAR dq_queue_t *list2,
                            uint8_t task_state);

I would represent that form as:

<subsystem>_<everythingelsesmooshedaltogether>

Many of these names are impossible to read unless you stop and parse the letters to find the word boundaries.

System-Object-Verb Naming

Most recent naming has broken out one more of the smooshed-together-words and separated them with undersore characters like:

unsigned int sched_timer_cancel(void);
void sched_timer_resume(void);
void sched_timer_reassess(void);

Which I would describe as:

<subsystem>_<object>_<verb>

System-Verb-Object Naming

Another form, which I have been using lately, is to switch the <object> and the <verb> like:

<subsystem>_<verb>_<object>

For example:

int sched_get_stackinfo(pid_t pid, FAR struct stackinfo_s *stackinfo);

By the <subsystem>_<object>_<verb> naming this would have been:

int sched_stackinfo_get(pid_t pid, FAR struct stackinfo_s *stackinfo);

And the timer interfaces would become the following under the <subsystem>_<verb>_<object> rule:

unsigned int sched_cancel_timerl(void);
void sched_resume_timer(void);
void sched_reassess_timer(void);

And the "smooshed" name sched_mergeprioritized() would become:

void sched_merge_prioritized(FAR dq_queue_t *list1, FAR dq_queue_t *list2,
                             uint8_t task_state);

I won't even consider the <subsystem>_<everythingelsesmooshedaltogether>. It has a history but is pretty much odious. We should not consider, for example, the smooshed-together form:

int sched_getstackinfo(pid_t pid, FAR struct stackinfo_s *stackinfo);

What an ugly mess!

Unit Suffixes

Often, you will have the functions that return the same value, but in different units. For example, these two functions return the system time:

clock_t clock_systimer(void);
int clock_systimespec(FAR struct timespec *ts);

The first returns the time in system clock ticks. The second returns the time as a struct timespec.

I have seen a naming practice The keeps the naming of the functions the same, but appends the units, preceded by an underscore character, at the end of the function name. For example, these could be:

clock_t clock_systime_ticks(void);
int clock_systime_timespec(FAR struct timespec *ts);

Or should they include a <verb>:

clock_t clock_get_systime_ticks(void);
int clock_get_systime_timespec(FAR struct timespec *ts);

That form would then be:

<subsystem>_<verb>_<object>[_<units>]

Where the square bracket represent and optional unit suffix.

Implicit get

In many cases, I think that the _get_ is implicit and need not appear in the function name. But if there are multiple operations on the <object>, then the _get_ would be necessary. Hence, I think the naming

clock_t clock_systime_ticks(void);
int clock_systime_timespec(FAR struct timespec *ts);

is perfectly accepable without the _get_. And since _get_ is the only operation on stackinfo, the following would be a perfectly acceptable renaming:

int sched_stackinfo(pid_t pid, FAR struct stackinfo_s *stackinfo);

Other Naming

There is other naming that uses long names with many underscore characters separating each word in the long name. I am personally not a fan of long names.

Conclusion

My preference would be the <subsystem>_<verb>_<object> form. I have been using this form in creating all new internal interfaces. Does anyone else have a thought? or a preference? We should come to an understanding and stop the arbitrary name changes. I hope that we can put an end to the smooshed-together naming (except wheree required) in any case.

NOTE: This applies only to the internal naming of functions within the OS. Other names are imposed on us by standards for application interfaces to the OS which may follow other rules.

  • No labels