|Version||alpha 110||Category||Documentation||Submitted by||Ladislav|
|Summary||The *-of function names violate the REBOL function naming convention documentation|
function names violate the REBOL function naming convention documented in http://www.rebol.com/r3/docs/concepts/scripts-style.html#section-10
In REBOL, we do not have to be rigid regarding function names, having the option to use whatever we like. Nevertheless, the practice of using the above kind of names confuses the users, not knowing what the REBOL function naming convention actually is. So, my suggestion is to:
- adjust the function naming convention and the mezzanine naming practice so, that they are mutually compatible
|Assigned to||n/a||Fixed in||-||Last Update||5-Mar-2014 09:31|
You are right: The naming convention docs should be updated to include the noun-of names.
The noun-of naming convention is used for functions that return a property of its argument, with the noun part being a descriptive name of the property. This is a new convention that was established for the reflectors (wrappers for the REFLECT function), but can be used for other functions that follow this model. It is a good idea to only use noun-of for intrinsic properties, rather than contents of container types. The noun-of functions are generally not used in conditional contexts, where adjective?, datatype? or question? are a better naming choices. It's probably a good idea for all noun-of functions to be non-modifying, since in general modifying functions should have a verb in there somewhere. Never use noun-of for functions that don't take an argument, and probably not if it takes more than one argument.
In addition to the reflectors, there are some other built-in functions that perhaps should be in noun-of form, notably INDEX-OF and LENGTH-OF (now INDEX? and LENGTH?). However, there is the legacy naming rule to consider in these cases: If a function existed in R2 and has carried over largely unchanged in semantics to R3, you keep the old name, even if you add a new name that might be better suited (with the possible exception of rarely used functions that are really badly named). And the additional new name gets added to R2/Forward, and backported to R2 if it gets enough consensus in the community. There are limits to #666: We try to minimize arbitrary incompatibilities between R2 and R3, only being incompatible when really necessary or in particular classes of functions.
On the other hand, this naming convention doesn't work with MAXIMUM-OF and MINIMUM-OF, which don't actually return the maximum or minimum of a series, they return the series at the position of the maximum or minimum. Gregg has suggested that these be renamed to FIND-MAX and FIND-MIN instead, and this will probably happen (rarely used, really badly named).
An alternative strategy would be to use the non-datatype-noun? convention instead of noun-of. However, historically the non-datatype-noun? convention has gotten the most complaints from the community, and the most calls for getting rid of it and using a different convention. This is why the noun-of convention was adopted in the first place. This doesn't include the implicit "is-" noun? functions, since they are kind of a philosophical extension of the datatype? functions.
An example of non-datatype-noun? is INFO?, which can probably get away with it because it can now be used in a conditional context - it returns none if there is no info.
I'd like to add my two cents about the ****? use specifically.
It would be nice for the convention to be also extended in order to specify that ****? be preferred in cases where they imply a Boolean return or more specifically REBOL "truthy' return values (false/none or something else).
As valid examples would be greater? odd? found?, integer? etc. Though I think this should not be a "strict" rule, it would be easier to apply if the ****-of rule was also added.
in a sense post-fixing ? would mean "Is this **** ?" instead of "what is **** of ?"
See also #1819 for another example of the adjective? vs. noun-of distinction.
Maxim, the "a Boolean return or more specifically REBOL truthy return values" thing is what is meant by "used in conditional contexts". That is where you find adjective?, implicit "is-" noun? (including datatype?), and most (but not all) question? names that have an answer that can be returned from the function (which is why WHY? is a valid exception). It's also sometimes used for functions that return an attribute of their argument that might not exist, where the existence or non-existence of the property is more often of interest than the property itself (i.e. EXISTS?); in those cases, an adjective? name is usually used and none is returned when you would want the condition to be not TRUE?.
EXISTS? is an interesting example of a function that has been and is still properly named. It used to be a strictly logical function, but was converted to a conditional function when it was determined that it could return more information than just file existence, and yet still be used as it was before. That is why it is still in adjective? form.
Suggesting AT-MAXIMUM and AT-MINIMUM for MAXIMUM-OF and MINIMUM-OF, like the AT word returns a series at an index position, they return the series at it's maximum or mininum position.
Having AT in the names emphasizes that it is the (repositioned) series itself which they return, not just one value.
I totally agree with Ch. we should also refurbish MAXIMUM-OF and MINIMUM-OF.
since the *-OF functions would serve as property getters, the above should return a single value (Not the input series), just like any other *-OF functions.
|FIND also returns the series at the position of the value found; FIND-MIN and FIND-MAX would make even more sense since we are searching for the value position. AT-MINIMUM and AT-MAXIMUM don't seem as appropriate since we don't specify or know the position ahead of time (like we do with AT). AT-MINIMUM? might make a good question function, but it doesn't seem to be a question that would be asked that often.|
|Ticket created for the MAXIMUM-OF and MINIMUM-OF naming issue: #1971|
|5-Mar-2014 09:31||BrianH||Status||Modified||submitted => reviewed|
|27-Feb-2013 06:30||BrianH||Comment : 0003527||Added||-|
|19-Feb-2012 19:22||BrianH||Comment : 0003225||Added||-|
|18-Jan-2011 20:08||maxim||Comment : 0003029||Modified||-|
|18-Jan-2011 20:08||maxim||Comment : 0003029||Added||-|
|12-Jan-2011 12:27||Ch.Ensel||Comment : 0003011||Modified||-|
|12-Jan-2011 12:25||Ch.Ensel||Comment : 0003011||Added||-|
|12-Jan-2011 01:49||BrianH||Comment : 0003005||Modified||-|
|12-Jan-2011 01:26||BrianH||Comment : 0003007||Added||-|
|12-Jan-2011 01:06||maxim||Comment : 0003006||Added||-|
|12-Jan-2011 00:32||BrianH||Comment : 0003005||Modified||-|
|12-Jan-2011 00:19||BrianH||Comment : 0003005||Added||-|
|12-Jan-2011 00:05||BrianH||Summary||Modified||The *-of function names violate the REBOL function naming convention => The *-of function names violate the REBOL function naming convention documentation|
|11-Jan-2011 23:46||BrianH||Comment : 0003004||Modified||-|
|11-Jan-2011 23:40||BrianH||Comment : 0003004||Added||-|
|11-Jan-2011 21:37||BrianH||Version||Modified||alpha 111 => alpha 110|