Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Change naming style for private functions #597

Merged
merged 2 commits into from
Apr 3, 2020
Merged

Change naming style for private functions #597

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fce18f4
Add prefix "_" underscore missing in private functions
Blast545 Mar 12, 2020
e2144b4
Change style for functions internal to module
Blast545 Mar 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions rcl/src/rcl/time.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,23 +32,23 @@ typedef struct rcl_ros_clock_storage_t

// Implementation only
rcl_ret_t
rcl_get_steady_time(void * data, rcl_time_point_value_t * current_time)
_rcl_get_steady_time(void * data, rcl_time_point_value_t * current_time)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does private function mean in C?
This function should be static, there's no naming convention needed.

According to the C++ standard, names starting with _ or names containing __ are reserved to the implementation. See https://wiki.sei.cmu.edu/confluence/display/cplusplus/DCL51-CPP.+Do+not+declare+or+define+a+reserved+identifier#DCL51-CPP.

I would rather delete leading underscores that add more.
We could use another convention for static functions, like s_, to make the name more obvious.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See old related discussion: ros2/rclcpp#874

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with you that by using static is enough so that the function is used only in the module.

I saw other functions with the leading underscore and wanted them to use the same naming convention. I can change this PR to remove the underscore and use the static keyword in all in the functions internal to the module.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I saw other functions with the leading underscore and wanted them to use the same naming convention

Having a naming convention is good but using a leading underscore is not standard compliant, so I would avoid that particular convention.
For the moment, I would just add static where missing. We can iterate on a correct naming convention later, maybe using s_ or maybe just using no prefix (i.e.: deleting current leading underscores).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I remove the leading underscore for the functions that already had it before my commit?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Private" in this case is indicating that it's not a public API intended to be stable for external reuse: https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#public-api-declaration It's about documentation more than enforcement.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The function in question can't be used externally anyways since it's not declared in a header.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the functions can't be used externally so it shouldn't be a problem related to API. I opened the issue because it's odd browsing through the code and not having some uniformity regarding names. e.g: rcl_init_generic_clock and _rcl_clock_generic_fini. I'll proceed removing the underscores and adding the static keyword instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The function in question can't be used externally anyways since it's not declared in a header.

IIRC, that's not 100% true. If the function isn't marked as static, you can declare it in another executable without definition, then link again this library and use it (that probably doesn't apply to Windows DLLs, because of their export/import stuff).
Functions not declared in a library header shouldn't be considered part of the API though.

I'll proceed removing the underscores and adding the static keyword instead.

👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's right, thanks for the clarification. Hopefully no one is adding a declaration anywhere.

{
(void)data; // unused
return rcutils_steady_time_now(current_time);
}

// Implementation only
rcl_ret_t
rcl_get_system_time(void * data, rcl_time_point_value_t * current_time)
_rcl_get_system_time(void * data, rcl_time_point_value_t * current_time)
{
(void)data; // unused
return rcutils_system_time_now(current_time);
}

// Internal method for zeroing values on init, assumes clock is valid
void
rcl_init_generic_clock(rcl_clock_t * clock)
_rcl_init_generic_clock(rcl_clock_t * clock)
{
clock->type = RCL_CLOCK_UNINITIALIZED;
clock->jump_callbacks = NULL;
Expand All @@ -60,11 +60,11 @@ rcl_init_generic_clock(rcl_clock_t * clock)
// The function used to get the current ros time.
// This is in the implementation only
rcl_ret_t
rcl_get_ros_time(void * data, rcl_time_point_value_t * current_time)
_rcl_get_ros_time(void * data, rcl_time_point_value_t * current_time)
{
rcl_ros_clock_storage_t * t = (rcl_ros_clock_storage_t *)data;
if (!t->active) {
return rcl_get_system_time(data, current_time);
return _rcl_get_system_time(data, current_time);
}
*current_time = rcutils_atomic_load_uint64_t(&(t->current_time));
return RCL_RET_OK;
Expand All @@ -91,7 +91,7 @@ rcl_clock_init(
switch (clock_type) {
case RCL_CLOCK_UNINITIALIZED:
RCL_CHECK_ARGUMENT_FOR_NULL(clock, RCL_RET_INVALID_ARGUMENT);
rcl_init_generic_clock(clock);
_rcl_init_generic_clock(clock);
return RCL_RET_OK;
case RCL_ROS_TIME:
return rcl_ros_clock_init(clock, allocator);
Expand Down Expand Up @@ -144,13 +144,13 @@ rcl_ros_clock_init(
{
RCL_CHECK_ARGUMENT_FOR_NULL(clock, RCL_RET_INVALID_ARGUMENT);
RCL_CHECK_ARGUMENT_FOR_NULL(allocator, RCL_RET_INVALID_ARGUMENT);
rcl_init_generic_clock(clock);
_rcl_init_generic_clock(clock);
clock->data = allocator->allocate(sizeof(rcl_ros_clock_storage_t), allocator->state);
rcl_ros_clock_storage_t * storage = (rcl_ros_clock_storage_t *)clock->data;
// 0 is a special value meaning time has not been set
atomic_init(&(storage->current_time), 0);
storage->active = false;
clock->get_now = rcl_get_ros_time;
clock->get_now = _rcl_get_ros_time;
clock->type = RCL_ROS_TIME;
clock->allocator = *allocator;
return RCL_RET_OK;
Expand Down Expand Up @@ -181,8 +181,8 @@ rcl_steady_clock_init(
{
RCL_CHECK_ARGUMENT_FOR_NULL(clock, RCL_RET_INVALID_ARGUMENT);
RCL_CHECK_ARGUMENT_FOR_NULL(allocator, RCL_RET_INVALID_ARGUMENT);
rcl_init_generic_clock(clock);
clock->get_now = rcl_get_steady_time;
_rcl_init_generic_clock(clock);
clock->get_now = _rcl_get_steady_time;
clock->type = RCL_STEADY_TIME;
clock->allocator = *allocator;
return RCL_RET_OK;
Expand All @@ -208,8 +208,8 @@ rcl_system_clock_init(
{
RCL_CHECK_ARGUMENT_FOR_NULL(clock, RCL_RET_INVALID_ARGUMENT);
RCL_CHECK_ARGUMENT_FOR_NULL(allocator, RCL_RET_INVALID_ARGUMENT);
rcl_init_generic_clock(clock);
clock->get_now = rcl_get_system_time;
_rcl_init_generic_clock(clock);
clock->get_now = _rcl_get_system_time;
clock->type = RCL_SYSTEM_TIME;
clock->allocator = *allocator;
return RCL_RET_OK;
Expand Down Expand Up @@ -363,7 +363,7 @@ rcl_set_ros_time_override(
if (storage->active) {
time_jump.clock_change = RCL_ROS_TIME_NO_CHANGE;
rcl_time_point_value_t current_time;
rcl_ret_t ret = rcl_get_ros_time(storage, &current_time);
rcl_ret_t ret = _rcl_get_ros_time(storage, &current_time);
if (RCL_RET_OK != ret) {
return ret;
}
Expand Down