The return value of TagGroupAddLabeledTagGroup

Question

For the command below, the return value is the src_tag_group. But I can't understand this design. If I need to use src_tag_group later, I can directly use it. Why this function returns it again?

TagGroup TagGroupAddLabeledTagGroup(TagGroup tgt_tag_group, String label, TagGroup src_tag_group)

Answer 1

I can also only speculate, as a lot of the scripting language syntax and curiosities go back 20years or more. Clean-ups have been rare in this time, mainly because "backward compatibility" of old scripts was deemed a lot more important than having a super clean and logical naming and syntax convention.

However, while redundant, returning the (just added) source tagGroup allows for some convenient "pipe-lining" as well, which might be part of why it is like that. ( I do that in a lot of my own classes, rather than returning a void. )

Example #1 - Pipe-line convenience

TagGroup TGparent = NewTagGroup() // Whatever parent. Might be a "ImageGetOrCreateTagGroup()
TGparent.TagGroupAddLabeledTagGroup("Group", NewTagGroup()).TagGroupSetTagAsString("Data","mine")
TGparent.TagGroupOpenBrowserWindow(0);

Example #2 - Adding & Variable assignment in one line

TagGroup TGparent = NewTagGroup();
TagGroup TGChild = TGparent.TagGroupAddLabeledTagGroup("Group 1", NewTagGroup())
TGChild.TagGroupSetTagAsString("Data","mine")
TGparent.TagGroupOpenBrowserWindow(0);

Answer 2

This answer is purely speculation, but perhaps someone with deeper inside knowledge can confirm, correct, or clarify it.

I suspect that this is a vestigial feature of an early implementation of the TagGroupAddLabeledTagGroup function in which a clone of the source TagGroup was added to the target TagGroup, so that subsequent changes to the added TagGroup would not impact the original source TagGroup, as illustrated by the following example:

TagGroup sourceTG = NewTagGroup();
sourceTG.TagGroupSetTagAsString("Data", "datum value");

TagGroup targetTG = NewTagGroup();
TagGroup clonedSourceTG = sourceTG.TagGroupClone();
TagGroup resultTG = targetTG.TagGroupAddLabeledTagGroup("Group 1", clonedSourceTG);
resultTG.TagGroupSetTagAsString("Data", "altered value");

sourceTG.TagGroupOpenBrowserWindow(0);
resultTG.TagGroupOpenBrowserWindow(0);

If this speculation is correct, then it was a convenience for TagGroupAddLabeledTagGroup to return a reference to the cloned subtag. However, given that the current implementation certainly does not do this sort of internal cloning of the source TagGroup, I agree that the return value is redundant and does not serve much purpose.