API Consistency: Parameters in constructors vs. static methods?

[sfiruch]

In the following example, we require parameters in three different places:

observation_settings = Observation(
    start_frequency_hz=100e6,
    phase_centre_ra_deg=phase_center[0],
    phase_centre_dec_deg=phase_center[1],
    number_of_channels=64,
    number_of_time_steps=24,
)

interferometer_sim = InterferometerSimulation(channel_bandwidth_hz=1e6)
visibility_askap = interferometer_sim.run_simulation(
    askap_tel, sky, observation_settings
)

• Observation constructor
• InterferometerSimulation constructor
• run_simulation function

Should we strive for more consistency? If so, in which direction?

Somewhat related, should we tend more towards static methods, or constructors:

fh = FileHandle()
fh.clean_up()

[sfiruch]

@Lukas113 @kenfus @rohitcbscient Opinions?

[Lukas113]

I think it makes sense to have a convention-document which describes how to organize code in general.

To me, the following makes sense:

• Create an object with parameters in the __init__ function where you need the parameters in the scope of the same object. This means, that these parameters should be relevant for current or future instance-bound functions or just serve as an object-storage.
• Instance-bound functions should make use of instance-variables (or possibly future instance-variables), otherwise you could just make a static or classmethod where the user doesn't has to bother about instancing of a class. Also for the developers it is clear that you don't bother about variable states other than static-variables.
• To me, instance-variables usually should have some persistent characteristics. This means, changing the content of an mutable instance-variable seems fine, but not change the reference itself very often just for variable sharing purpose. I think handling something like this with a return is usually better.

So to conclude, to me it seems fine to pass parameters, provide static functions or create objects wherever it makes sense to do so. Also, in my opinion more consistency is desired. I would also recommend to create more protected/private functions where we don't care about API consistency, but for public functions we should. So changing private/protected code (where we care about implementation details) doesn't cause an immediate API breaking change each time we release a new version.

I think this answers the questions you stated to some extend?