[Scons-users] conventions for AddMethod

[Mats Wichmann]

Is there a best-known convention for the use of AddMethod, as in "use
same name as function" or "use different name than function"?

The docs render no opinion on this as both ways obviously work:

When called with the AddMethod() form, adds the specified function to
the specified object as the specified method name. When called with the
env.AddMethod() form, adds the specified function to the construction
environment env as the specified method name. In both cases, if name is
omitted or None, the name of the specified function itself is used for
the method name.

The reason I ask is that if the names are different, it is what you
might call an "IDE confuser" (including IDE-like helpers like ctags)
where it is expected you can associate a call reference in the code with
a function defined somewhere in the code but you don't have that
relationship. No environment I know of understands the scons AddMethod
to make the binding.

Many places in the scons code itself use the same name:

src/engine/SCons/Tool/javac.py:
env.AddMethod(Java)

src/engine/SCons/Tool/docbook/__init__.py:
env.AddMethod(DocbookPdf, "DocbookPdf")


But some do not:

src/engine/SCons/Tool/gettext_tool.py:
env.AddMethod(_translate, 'Translate')

src/engine/SCons/Tool/xgettext.py:
env.AddMethod(_POTUpdateBuilderWrapper, 'POTUpdate')


naturally, my project has chosen the second style, where the function
def uses some "hidden" (underscore-prefixed) name and then adds it with
a different public name. Thus leaving me occasionally frustrated. I'll
try to change these, but was looking for ammunition I might use in the
discussion if there is pushback :) Pros or cons of one form over the
other?

[Bill Deegan]

I have not strong opinions on this one.

Pythonically the _ should represent functions which shouldn't get called
(or called directly) from outside the module.
I'm not sure in any case calling any of the methods added via AddMethod
outside of the env, or DefaultEnvironment make sense.
So you could argue _ should be used for all of them.

That said, I don't think it's worth changing all the existing code from one
to the other.
(Lots of other tasks to be done would provide more utility for the project).

-Bill

Post by Mats Wichmann
Is there a best-known convention for the use of AddMethod, as in "use
same name as function" or "use different name than function"?
When called with the AddMethod() form, adds the specified function to
the specified object as the specified method name. When called with the
env.AddMethod() form, adds the specified function to the construction
environment env as the specified method name. In both cases, if name is
omitted or None, the name of the specified function itself is used for
the method name.
The reason I ask is that if the names are different, it is what you
might call an "IDE confuser" (including IDE-like helpers like ctags)
where it is expected you can associate a call reference in the code with
a function defined somewhere in the code but you don't have that
relationship. No environment I know of understands the scons AddMethod
to make the binding.
env.AddMethod(Java)
env.AddMethod(DocbookPdf, "DocbookPdf")
env.AddMethod(_translate, 'Translate')
env.AddMethod(_POTUpdateBuilderWrapper, 'POTUpdate')
naturally, my project has chosen the second style, where the function
def uses some "hidden" (underscore-prefixed) name and then adds it with
a different public name. Thus leaving me occasionally frustrated. I'll
try to change these, but was looking for ammunition I might use in the
discussion if there is pushback :) Pros or cons of one form over the
other?
_______________________________________________
Scons-users mailing list
https://pairlist4.pair.net/mailman/listinfo/scons-users

[Mats Wichmann]

Post by Bill Deegan
I have not strong opinions on this one.
Pythonically the _ should represent functions which shouldn't get called
(or called directly) from outside the module.
I'm not sure in any case calling any of the methods added via AddMethod
outside of the env, or DefaultEnvironment make sense.
So you could argue _ should be used for all of them.
That said, I don't think it's worth changing all the existing code from one
to the other.
(Lots of other tasks to be done would provide more utility for the project).

To be clear (if it wasn't), I was not proposing any changes to scons, I
was trying to note that the scons source code did not provide a
"consensus opinion" since both ways are used.

In my specific case, if I have a tags file, and I'm editing in vim, and
I have the cursor on what looks like a function call and press ^] to
jump to that function, if the name was created by AddMethod to refer to
an actual function of a different name, then there just won't be a tag
to jump to, as ctags has no idea about this binding. Or if I have an
IDE and want to hover over the name to have it display call tips, there
would be nothing there, because the function has a different name.

Meanwhile, there's certainly validity to the viewpoint that these
functions should not be called outside of their special context and so
"hiding" them (in the limited sense Python can do that) makes some sense.

[Bill Deegan]

I wonder if there's a way to add the info to your ctags file?

Post by Bill Deegan

Post by Bill Deegan
I have not strong opinions on this one.
Pythonically the _ should represent functions which shouldn't get called
(or called directly) from outside the module.
I'm not sure in any case calling any of the methods added via AddMethod
outside of the env, or DefaultEnvironment make sense.
So you could argue _ should be used for all of them.
That said, I don't think it's worth changing all the existing code from

one

Post by Bill Deegan
to the other.
(Lots of other tasks to be done would provide more utility for the

project).
To be clear (if it wasn't), I was not proposing any changes to scons, I
was trying to note that the scons source code did not provide a
"consensus opinion" since both ways are used.
In my specific case, if I have a tags file, and I'm editing in vim, and
I have the cursor on what looks like a function call and press ^] to
jump to that function, if the name was created by AddMethod to refer to
an actual function of a different name, then there just won't be a tag
to jump to, as ctags has no idea about this binding. Or if I have an
IDE and want to hover over the name to have it display call tips, there
would be nothing there, because the function has a different name.
Meanwhile, there's certainly validity to the viewpoint that these
functions should not be called outside of their special context and so
"hiding" them (in the limited sense Python can do that) makes some sense.
_______________________________________________
Scons-users mailing list
https://pairlist4.pair.net/mailman/listinfo/scons-users