Methods naming

[antonkomarev]

The most hardest part is choose right names for methods which wouldn't confuse developer what exactly will be done.

Preface

At the start of the package live I've chosen a naming concept where unset flag method should use verbose antonym of set method. This was a good choice at the start point, but with each new flag there were harder to strictly follow this convention.

Current flags methods

Flag name	Set method	Unset method	Scope methods postfix
Classic\Accepted	accept	unaccept	*Unaccepted
Classic\Active	activate	deactivate	*Inactive
Classic\Approved	approve	unapprove	*Unapproved
Classic\Kept	keep	unkeep	*Unkept
Classic\Opened	open	???	*Closed
Classic\Published	publish	unpublish	*Unpublished
Classic\Verified	verify	unverify	*Unverified
Inverse\Closed	close	???	*Closed
Inverse\Expired	expire	unexpire	*Expired

Issue 1 (not exists antonyms): I haven't found any verbose antonym for expire word (valid isn't a good one because it's opposite of invalid). After that I had to add one more not exists word unexpire. Same case was issued with verify and keep. Things started to be not so clear.

Issue 2 (same words for logically different flags): Then Classoc\Approved and Classic\Accepted flags were introduced. Both of this words has similar antonyms: Refuse, Reject, Decline. When I see decline method in code, I'm not sure is it decline of an Approved flag or decline of an Accepted flag? By example of expired and verified flags I've used one more not exists word unapprove for unset flag method of an Approved flag, but it's started to ruin standard. Now I see that I missed possibility to use disapprove method for approve and reject for accept but there could be other words with same issue.

Issue 3 (methods name intersection): After flags with inverse logic were introduced there one more issue revealed. Both of the Inverse\Closed and Classic\Opened flags has open and close methods which leads to conflict in case of simultaneous use. It's not critical, because there are no use cases was found for it but should be considered and documented.

Finally I've decided to choose one naming concept and follow if for all future releases. There are 3 naming concepts I can see so far. Each has own pros and cons.

1. Flag unset methods names are antonyms of set method

All unset flag methods SHOULD use antonyms of the set flag method name.

Pros:

• Intuitive. It looks obvious that if you need to remove active flag from model - you should deactivate it.
• Follow English language grammar.

Cons:

• Issue 1 (not exists antonyms). Words expire, verify, keep don't have any verbose antonyms which will be clearly understood by developer as opposite of these ones without diving into the code or docs.
• Issue 2 (same words for logically different flags). Refuse, Reject, Decline are antonyms for both of the words Accept and Approve.
• Issue 3 (methods name intersection). Closed inverse flag has conflicts with Opened classic flag.

Flags methods

Flag name	Set method	Unset method	Scope methods postfix
Classic\Accepted	accept	reject	*Rejected
Classic\Active	activate	deactivate	*Deactivated
Classic\Approved	approve	disapprove	*Disapproved
Classic\Kept	keep	unkeep	*Unkept
Classic\Opened	open	close	*Closed
Classic\Published	publish	unpublish	*Unpublished
Classic\Verified	verify	unverify	*Unverified
Inverse\Closed	close	open	*Closed
Inverse\Expired	expire	unexpire	*Expired

2. Flag unset methods names starts with un

All unset flag methods SHOULD have un prefix. Not exists words will be used then: unaccept, unactivate, unapprove, unexpire, unclose.

Pros:

• Solves Issue 1 (not exists antonyms). No worry about antonyms. Just add prefix to unset name.
• Solves Issue 2 (same words for logically different flags). It wouldn't matter if antonym could be valid for more than one word. decline and reject could be treated as unset methods for accept and approve methods, but unaccept and unapprove not.
• Partially solves Issue 3 (methods name intersection). Closed flag will have close & unclose methods and Opened flag will have open & unopen methods, what allows us to use them in one model. This isn't a silver bullet anyway because such flags as Unpublished or any other words which has antonym prefixed with un are still be bugged.
• Consistent naming convention. If you want to unset flag - you should just add un prefix to it's name.
• Easier to remember. It's easier to remember opposite name of the action because it's always will just add a prefix.

Cons:

• Bye grammar. And hello a whole bunch of not exists words in your code.

Flags methods

Flag name	Set method	Unset method	Scope methods postfix
Classic\Accepted	accept	unaccept	*Unaccepted
Classic\Active	activate	unactivate	*Unactivated
Classic\Approved	approve	unapprove	*Unapproved
Classic\Kept	keep	unkeep	*Unkept
Classic\Opened	open	unopen	*Unopened
Classic\Published	publish	unpublish	*Unpublished
Classic\Verified	verify	unverify	*Unverified
Inverse\Closed	close	unclose	*Closed
Inverse\Expired	expire	unexpire	*Expired

3. Both of these concepts should work

Both of previous concepts SHOULD be implemented. All unset flag methods will have prefix un in name and it's alias named as antonym of the set flag method.

That will create reject and unaccept methods as opposite of accept.

Pros:

• Solves Issue 1 (not exists antonyms). No worry about antonyms. Just add prefix to unset name.
• Solves Issue 2 (same words for logically different flags). It wouldn't matter if antonym could be valid for more than one word. decline and reject could be treated as unset methods for accept and approve methods, but unaccept and unapprove not.
• Partially solves Issue 3 (methods name intersection). Closed flag will have close & unclose methods and Opened flag will have open & unopen methods, what allows us to use them in one model. This isn't a silver bullet anyway because such flags as Unpublished or any other words which has antonym prefixed with un are still be bugged.
• Follow English language grammar.
• Intuitive. It looks obvious that if you need to remove active flag from model - you should deactivate it.
• Free to choose. Developer can choose what does he likes.

Cons:

• Naming inconsistency.
• Namespace narrowing. Aliases spam isn't very good because of increasing possibility of methods name intersection with other packages.

Flags methods

Flag name	Set method	Unset method	Scope methods postfix
Classic\Accepted	accept	reject & unaccept	*Unaccepted & *Rejected
Classic\Active	activate	deactivate & unactivate	*Unactivated & *Deactivated
Classic\Approved	approve	disapprove & unapprove	*Unapproved & *Disapproved
Classic\Kept	keep	unkeep	*Unkept
Classic\Opened	open	close & unopen	*Closed
Classic\Published	publish	unpublish	*Unpublished
Classic\Verified	verify	unverify	*Unverified
Inverse\Closed	close	open & unclose	*Closed
Inverse\Expired	expire	unexpire	*Expired

Conclusion

If concept no. 1 will be accepted these methods will be affected:

• unaccept -> reject
• unapprove -> disapprove
• *Unaccepted -> *Rejected
• *Inactive -> *Deactivated
• *Unapproved -> *Disapproved

Problems with antonyms for words like verify and expire wouldn't be resolved. As exception for words which doesn't have verbose antonym un prefix will be used still.

If concept no. 2 will be accepted these methods will be affected:

• deactivate -> unactivate
• *Inactive -> *Unactivated
• *Closed -> *Unopened

[antonkomarev]

First concept will be used in all future flags. In v3.0 all current flags methods will be renamed to follow the naming convention.