should provide advice on when it's good to return the same object again

[dbaron]

As a followup to #34 (which I will make a pull request for shortly), I think the document should provide advice on when it's acceptable / good for an API to return the same object repeatedly, versus when it should return a new object each time. This advice presumably differs for methods versus attribute getters (since there are cases when attributes are required to return the same object), and also for live versus static objects (since live objects allow more flexibility to return the same object).

The section addressing this should probably be near the section added by #34.

[domenic]

Related, but not necessarily redundant: https://w3ctag.github.io/design-principles/#attributes-like-data

[dbaron]

From TAG discussion today: perhaps the methods versus attributes thing is even the other way around: if you're returning the same object again, you should have an attribute; if you're always creating a new object, you should have a method.

[torgo]

@dbaron to write some text.

[dbaron]

@cynthia and I just discussed this a little bit in a breakout.

I think the most normal cases are:

• function or attribute getter returns live object, and it's the same object each time
• function return static object/state, and it's a new object each time

I believe there are a bunch of exceptions to this on the web platform, but we didn't get to the point of trying to make a list of them. I think the interesting question about these exceptions is: are any of them good? If so, why?

I think if we can answer that, we can probably provide useful advice here.

[annevk]

I think there's at least one other case, very common in node trees:

• method or getter from an object A returns an object from an internal slot and that internal slot can be manipulated, potentially causing another things to be returned when it is manipulated. (E.g., firstChild.)

[dbaron]

I think the case @annevk mentions in #46 (comment) is probably not a separate case, but rather digging into the subtlety about what we mean by "the same object each time". In other words, things where we're saying the normal thing is "return the same object each time" don't necessarily return the same object all the time; for many such cases there are state changes that cause the object it returns to change. (But there are also a bunch where there are no such state changes.)

On the other hand, maybe it is worth describing those as separate cases, but I wasn't really thinking of them as such.

[dbaron]

@cynthia is likely going to try to address both this and #70 in the same PR.

[annevk]

@dbaron that's fair. When I read "same object each time" I see [SameObject] (which one day will be made useful and renamed to [Cached]). And given that terminology from IDL you probably do want to be explicit about it.

[cynthia]

This was addressed in #70, but never closed.