Subroutine naming convention/style

Cody Fendant has asked for the wisdom of the Perl Monks concerning the following question:

I'm trying to write code to access an API.

In that API there's an "either add or update" method for an object.

Whether you're adding or updating that object, you provide an ID. If that ID is found in their database, then you're updating that object. If not, you're adding it.

What would you call your subroutine which either added or updated a Widget?

Would you call it: addOrUpdateWidget() because that at least matches their API call (longwinded names are all over the place).

Would you have two subroutines addWidget() and updateWidget() to make it more transparent what the user was trying to do, and let you give a warning "you thought you were updating a Widget! Turns out you added it instead."?

Would you call it just widget()?

Comment on Subroutine naming convention/style Select or Download Code

Replies are listed 'Best First'.
Re: Subroutine naming convention/style by kcott (Archbishop) on Oct 07, 2015 at 06:13 UTC
G'day Cody Fendant, I would keep the base operations separate and clearly named to indicate their functions: `$self->add_widget($id, @other_args)` which potentially emits: "`Widget already exists!`" `$self->update_widget($id, @other_args)` which potentially emits: "`Widget does not exist!`" This allows you to unambiguously call the method you want directly and get feedback for errors. For your "either add or update" function, what you're doing is modifying your set of widgets. I'd give it a name that exactly reflects that: `$self->modify_widget_set($id, @other_args)` [download] This would call either `add_widget()` or `update_widget()` depending on the existence of `$id` in the database. The method names I've shown are just suggestions. I'm not a big fan of CamelCase; however, if this is already used throughout your codebase, it would make sense to stick with it (`addWidget()`, `modifyWidgetSet()`, etc.). "Would you call it just `widget()`?" Short answer: Never! Longer answer: Subroutines do something and their names should reflect this. Use verbs (or, at least, something suggesting a verb). — Ken	[reply] [d/l] [select]
Re: Subroutine naming convention/style (set, config) by tye (Sage) on Oct 07, 2015 at 04:45 UTC
We have used: setWidget(), configWidget(). It is also close to "upsert" (update or insert). - tye	[reply]
Re: Subroutine naming convention/style by Your Mother (Archbishop) on Oct 07, 2015 at 12:09 UTC
The temptation to improve awkward, or even just poor, interfaces is strong but I would echo their call names exactly (unless you are writing a much higher level abstraction/client for the API). Then their documentation is useful for your code consumers and there are fewer parts to drift or cause confusion down the road.	[reply]
Re: Subroutine naming convention/style by dsheroh (Monsignor) on Oct 07, 2015 at 09:05 UTC
I'd go with `set_widget`, because that's what the user wants to do. I would also provide `add_widget` and `update_widget` functions for the rare cases where the user cares whether the widget previously existed or not, but, in my experience, 99% of the time, you don't care about that, you only care that, when the operation completes, the widget will be there. So I wouldn't expect them to be used nearly as often as `set_widget`, but they should still be there for completeness.	[reply] [d/l] [select]
A reply falls below the community's threshold of quality. You may see it by logging in.