need a standard for contrib node build_mode constants

[Peter Wolanin]

When doing some cleanup of my Modr8 module, I wanted to define a new
build_mode for use by
http://api.drupal.org/api/function/node_build_content/6

I realized that we don't have any standard for picking new int
constants for this case in specific, or more generally.  So, here's a
suggested standard that I think is nearly fool-proof:  When defining
an additional build mode constant (or similar constant) in a
contributed module, the suggested standard is to use the unix
timestamp of when you write the code to minimize the likelihood of two
modules using the same value.

I think it's sane and nearly perfect since a new module will then
never pick the same value as an existing module, and in general it's
very unlikely that 2 people will by writing a new constant the same
second.

Am I missing anything?  Any reason not to suggest this as a standard?

-Peter

PS - a couple easy ways to get the timestamp on you command line:

date -j "+%s"
php -r 'echo time() ."\n";'

[Earl Miles]

Peter Wolanin wrote:
> When doing some cleanup of my Modr8 module, I wanted to define a new
> build_mode for use by
> http://api.drupal.org/api/function/node_build_content/6

I believe there is no need to stick with ints; CCK uses this and I think
it's using strings.

[Peter Wolanin]

The reason I was suggesting sticking with ints is that strings are
cast to int 0 during comparison:

php -r"var_dump('cck' == 0);"

bool(true)

And core has code like:

modules/upload/upload.module:363:  if ($node->build_mode == NODE_BUILD_RSS) {

modules/book/book.module:710:    if (!empty($node->book['bid']) &&
$node->build_mode == NODE_BUILD_NORMAL) {

So if CCK is using ints, that's a potentially serious bug - 0 is
NODE_BUILD_NORMAL, so I think any string build modes will basically
end up being this mode.

-Peter

On Sat, May 16, 2009 at 11:50 PM, Earl Miles <merlin@...> wrote:
> Peter Wolanin wrote:
>>
>> When doing some cleanup of my Modr8 module, I wanted to define a new
>> build_mode for use by
>> http://api.drupal.org/api/function/node_build_content/6
>
> I believe there is no need to stick with ints; CCK uses this and I think
> it's using strings.
>

[Larry Garfield]

Peter's suggestion may work for D6, but for D7, I refer people to
Eaton's "How to make good APIs" session from DCDC.  Digest version: If
you expect people to extend your list of flags/constants/modes, for the
love of god use strings, not ints.  Ints WILL break.  Don't be stupid,
use strings.

So it sounds like if we expect people to extend the build modes from
contrib, then core should switch from ints to strings anyway.  Who wants
to roll the patch? :-)

--Larry Garfield

Peter Wolanin wrote:

> The reason I was suggesting sticking with ints is that strings are
> cast to int 0 during comparison:
>
> php -r"var_dump('cck' == 0);"
>
> bool(true)
>
> And core has code like:
>
> modules/upload/upload.module:363:  if ($node->build_mode == NODE_BUILD_RSS) {
>
> modules/book/book.module:710:    if (!empty($node->book['bid']) &&
> $node->build_mode == NODE_BUILD_NORMAL) {
>
> So if CCK is using ints, that's a potentially serious bug - 0 is
> NODE_BUILD_NORMAL, so I think any string build modes will basically
> end up being this mode.
>
> -Peter
>
> On Sat, May 16, 2009 at 11:50 PM, Earl Miles <merlin@...> wrote:
>> Peter Wolanin wrote:
>>> When doing some cleanup of my Modr8 module, I wanted to define a new
>>> build_mode for use by
>>> http://api.drupal.org/api/function/node_build_content/6
>> I believe there is no need to stick with ints; CCK uses this and I think
>> it's using strings.
>>

[Moshe Weitzman]

Peter clarified in IRC that his timestamp proposal for for D6 and that
we should use strings for D7. And yes, we need a patch at
http://drupal.org/node/409750

On Mon, May 18, 2009 at 3:13 PM, larry@...
<larry@...> wrote:

> Peter's suggestion may work for D6, but for D7, I refer people to Eaton's
> "How to make good APIs" session from DCDC.  Digest version: If you expect
> people to extend your list of flags/constants/modes, for the love of god use
> strings, not ints.  Ints WILL break.  Don't be stupid, use strings.
>
> So it sounds like if we expect people to extend the build modes from
> contrib, then core should switch from ints to strings anyway.  Who wants to
> roll the patch? :-)
>
> --Larry Garfield
>
> Peter Wolanin wrote:
>>
>> The reason I was suggesting sticking with ints is that strings are
>> cast to int 0 during comparison:
>>
>> php -r"var_dump('cck' == 0);"
>>
>> bool(true)
>>
>> And core has code like:
>>
>> modules/upload/upload.module:363:  if ($node->build_mode ==
>> NODE_BUILD_RSS) {
>>
>> modules/book/book.module:710:    if (!empty($node->book['bid']) &&
>> $node->build_mode == NODE_BUILD_NORMAL) {
>>
>> So if CCK is using ints, that's a potentially serious bug - 0 is
>> NODE_BUILD_NORMAL, so I think any string build modes will basically
>> end up being this mode.
>>
>> -Peter
>>
>> On Sat, May 16, 2009 at 11:50 PM, Earl Miles <merlin@...> wrote:
>>>
>>> Peter Wolanin wrote:
>>>>
>>>> When doing some cleanup of my Modr8 module, I wanted to define a new
>>>> build_mode for use by
>>>> http://api.drupal.org/api/function/node_build_content/6
>>>
>>> I believe there is no need to stick with ints; CCK uses this and I think
>>> it's using strings.
>>>
>

[Karoly Negyesi]

On Mon, May 18, 2009 at 12:13 PM, larry@...
<larry@...> wrote:
> Peter's suggestion may work for D6, but for D7, I refer people to Eaton's
> "How to make good APIs" session from DCDC.  Digest version: If you expect
> people to extend your list of flags/constants/modes, for the love of god use
> strings, not ints.  Ints WILL break.  Don't be stupid, use strings.

Hummm.

Ints, strings, these are just ways to express bits of information.

Each character of a string will have approx 5 bit of info (or a bit
less, 26 english chars, underscore, thats 27 not 32 but lets say 32).
It also must be noted that its unlikely you will use all possible
combinations, I bet XRNQW will not be used for example...

I am with Peter, his proposal makes sense to me and can code more
possibilities than strings.

[Jeff Eaton]

The problem is not one of information storage length, but of flag  
collision.

Ints are fine as primary keys on a lookup table, or constant values  
for internal flags that will never be extensible. For things we know  
people will build on -- like node types, or node build modes --  
strings are the only way to avoid collisions when module developers  
start expanding.

--Jeff

On May 18, 2009, at 3:27 PM, Karoly Negyesi wrote:

> Ints, strings, these are just ways to express bits of information.
>
> Each character of a string will have approx 5 bit of info (or a bit
> less, 26 english chars, underscore, thats 27 not 32 but lets say 32).
> It also must be noted that its unlikely you will use all possible
> combinations, I bet XRNQW will not be used for example...
>
> I am with Peter, his proposal makes sense to me and can code more
> possibilities than strings.

[Karoly Negyesi]

To the contrary, Peter's proposition makes a very good standard to
avoid collisions, it's actually better than strings IMO.

[Earl Miles]

Karoly Negyesi wrote:
> To the contrary, Peter's proposition makes a very good standard to
> avoid collisions, it's actually better than strings IMO.

Hardly. You have an int that has no real meaning and then a string
anyway, which is the define. The *only* improvement is that in theory a
32 bit int is slightly faster to look up via index.

[John VanDyk]

>To the contrary, Peter's proposition makes a very good standard to
>avoid collisions, it's actually better than strings IMO.

To really make it unique, you'd want to prepend your drupal.org uid
and append your shoe size.

[Chris Johnson-21]

Maybe I'm missing something here, but it's just as possible to
accidentally re-use a string constant as a numeric constant.  How does
using a string help things at all?  Either the developer reads and
enumerates a list of all existing uses and avoids collision -- or does
not -- regardless of whether they are integers, strings, or ice cream
flavors.

Please educate me!

..chris

On Tue, May 19, 2009 at 12:12 PM, John VanDyk <jvandyk@...> wrote:
>> To the contrary, Peter's proposition makes a very good standard to
>> avoid collisions, it's actually better than strings IMO.
>
> To really make it unique, you'd want to prepend your drupal.org uid and
> append your shoe size.
>

[Earl Miles]

Chris Johnson wrote:
> Maybe I'm missing something here, but it's just as possible to
> accidentally re-use a string constant as a numeric constant.  How does
> using a string help things at all?  Either the developer reads and
> enumerates a list of all existing uses and avoids collision -- or does
> not -- regardless of whether they are integers, strings, or ice cream
> flavors.
>
> Please educate me!

Strings have meaning. Ints do not. Therefore if there is a collision it
is at least a collision over meaning.

[Steve Ringwood]

With string constants you follow (or at least should) the naming
convention that the first part is the module name.

nevets

[Robert Douglass]

Or we could have a factory function that takes a string hint and  
returns a lightweight object based on the hint. This might actually  
open the door to making the build mode useful, as you could delegate  
build-mode specific actions to the build mode object. It would also  
make the system extensible because you could provide a sub-class of  
any existing build mode object and the factory function would have to  
return that instead, even though you had passed in the same hint.

Robert Douglass

The RobsHouse.net Newsletter: http://robshouse.net/newsletter/robshousenet-newsletter
Follow me on Twitter: http://twitter.com/robertDouglass

On May 19, 2009, at 8:08 PM, Earl Miles wrote:

> Chris Johnson wrote:
>> Maybe I'm missing something here, but it's just as possible to
>> accidentally re-use a string constant as a numeric constant.  How  
>> does
>> using a string help things at all?  Either the developer reads and
>> enumerates a list of all existing uses and avoids collision -- or  
>> does
>> not -- regardless of whether they are integers, strings, or ice cream
>> flavors.
>> Please educate me!
>
> Strings have meaning. Ints do not. Therefore if there is a collision  
> it is at least a collision over meaning.

[Earnie]

Quoting Jeff Eaton <jeff@...>:

> The problem is not one of information storage length, but of flag collision.
>
> Ints are fine as primary keys on a lookup table, or constant values  
> for internal flags that will never be extensible. For things we know  
> people will build on -- like node types, or node build modes --  
> strings are the only way to avoid collisions when module developers  
> start expanding.
>

The only way to avoid a collision between developers of modules is to  
create a namespace based on the module name for whatever the data is.  
So for node_type a unique key of module and name creates the necessary  
uniqueness required.  The system though needs to include the module  
for the content type in it's presentation so that one knows by looking  
at the UI which module the content type is for.  Perhaps the use of  
fieldsets where the fieldset is the module name could help clear up  
the confusion when more than one module could create a UI data conflict.

--
Earnie
-- http://r-feed.com/           -- http://for-my-kids.com/
-- http://www.4offer.biz/       -- http://give-me-an-offer.com/

[Jeff Eaton]

Indeed.

At least with strings it's possible to develop meaningful conventions.  
With ints, there is literally no meaning other than "first come, first  
served, set up a registry."

--Jeff


On May 19, 2009, at 1:57 PM, Earnie Boyd wrote:

> Quoting Jeff Eaton <jeff@...>:
>
>> The problem is not one of information storage length, but of flag  
>> collision.
>>
>> Ints are fine as primary keys on a lookup table, or constant values  
>> for internal flags that will never be extensible. For things we  
>> know people will build on -- like node types, or node build modes  
>> -- strings are the only way to avoid collisions when module  
>> developers start expanding.
>>
>
> The only way to avoid a collision between developers of modules is  
> to create a namespace based on the module name for whatever the data  
> is.  So for node_type a unique key of module and name creates the  
> necessary uniqueness required.  The system though needs to include  
> the module for the content type in it's presentation so that one  
> knows by looking at the UI which module the content type is for.  
> Perhaps the use of fieldsets where the fieldset is the module name  
> could help clear up the confusion when more than one module could  
> create a UI data conflict.

[Chris Johnson-21]

After all, we wouldn't want developers to have actually document
anything they write.  ;-)

On Wed, May 20, 2009 at 1:04 PM, Jeff Eaton <jeff@...> wrote:

> Indeed.
>
> At least with strings it's possible to develop meaningful conventions. With
> ints, there is literally no meaning other than "first come, first served,
> set up a registry."
>
> --Jeff
>
>
> On May 19, 2009, at 1:57 PM, Earnie Boyd wrote:
>
>> Quoting Jeff Eaton <jeff@...>:
>>
>>> The problem is not one of information storage length, but of flag
>>> collision.
>>>
>>> Ints are fine as primary keys on a lookup table, or constant values for
>>> internal flags that will never be extensible. For things we know people will
>>> build on -- like node types, or node build modes -- strings are the only way
>>> to avoid collisions when module developers start expanding.
>>>
>>
>> The only way to avoid a collision between developers of modules is to
>> create a namespace based on the module name for whatever the data is.  So
>> for node_type a unique key of module and name creates the necessary
>> uniqueness required.  The system though needs to include the module for the
>> content type in it's presentation so that one knows by looking at the UI
>> which module the content type is for.  Perhaps the use of fieldsets where
>> the fieldset is the module name could help clear up the confusion when more
>> than one module could create a UI data conflict.
>

[Earnie]

Quoting Chris Johnson <cxjohnson@...>:

> After all, we wouldn't want developers to have actually document
> anything they write.  ;-)
>

It isn't the developer of the module that would be confused.  It would  
be the users of the module that would be confused and users rarely  
read the documentation because the developer is too technical with it.  
  User initial experience of a product gears toward is the product  
self documenting or in other words natural to use.

--
Earnie
-- http://r-feed.com/           -- http://for-my-kids.com/
-- http://www.4offer.biz/       -- http://give-me-an-offer.com/

[Jeff Eaton]

On May 21, 2009, at 11:50 AM, Chris Johnson wrote:

> After all, we wouldn't want developers to have actually document
> anything they write.  ;-)

Well... documentation is needed in either case. But with ints,  
collisions are absolutely inevitable. I ran into this with VotingAPI  
early on -- I had a const for 'vote_type', and it had 3 values out of  
the box. Pretty quickly, two other modules both defined fourth value  
types. suddenly, those modules couldn't co-exist with each other.

There's nothing in *my* documentation that could have solved that,  
other than a pointer to a wiki page where everyone claimed ints.

[Mike O'Connor-7]

I think the best example of using strings over ints is DNS.  How many people know IP address of their favorite website? Using a numeric based name space is great for machines, but in order for the web to be usable, we had to create DNS.

I suspect the same logic would apply here. If we are going to have a usable api, we should use a string.

Mike O.

With that in mind, you would have to do a lot to convince me that int's were a better solution for an API. 

On Thu, May 21, 2009 at 3:09 PM, Jeff Eaton <jeff@...> wrote:

On May 21, 2009, at 11:50 AM, Chris Johnson wrote:

After all, we wouldn't want developers to have actually document
anything they write.  ;-)

Well... documentation is needed in either case. But with ints, collisions are absolutely inevitable. I ran into this with VotingAPI early on -- I had a const for 'vote_type', and it had 3 values out of the box. Pretty quickly, two other modules both defined fourth value types. suddenly, those modules couldn't co-exist with each other.

There's nothing in *my* documentation that could have solved that, other than a pointer to a wiki page where everyone claimed ints.