2

I am working with a system that connects a number of voltage reference devices to a measurement device, it does this by "setting a relay".

When defining the name of this function I have a feeling that SetRelay conveys the idea of setting some property of the software object rather than setting the physical relay to the set position.

Connect and Close feel like a poor options as the relays have 2 "connections" which within the problem domain we refer to as "set" and "reset". the relay is either connected to set or to reset saying CloseRelay or ConnectRelay does not convey which contact is being closed/connected.

I think SetRelay is misleading to a programmer but is likely what the Domain experts would expect the function to be called.

How should one handle situation like this? What should the function be called? Am I over thinking it and SetRelay is fine?

5
  • 2
    Is the audience for this function primarily the domain experts or the programmers? Commented Jul 19, 2023 at 18:04
  • That’s why sorting method names in alphabetical order is a bad idea :-)
    – gnasher729
    Commented Jul 19, 2023 at 18:37
  • @RobertHarvey The audience likely leans more toward the domain experts, they are often the ones who end up handling general maintenance on the system once it is fully released. They are also all Electrical engineers with some familiarity with programming but it is not their primary discipline.
    – Nifim
    Commented Jul 19, 2023 at 19:01
  • I know you have already nominated an answer, but I want to know why your code is referring to the action of turning the relay on, and not the behavior of what is happening (Connecting various voltage reference devices)?
    – Peter M
    Commented Jul 19, 2023 at 21:44
  • @PeterM there are higher level that do refer to the action as for example Connect10VRef() but that function must in turn call a function that "sets" the relay for the connection, which is done by sending serial commands to a piece of hardware
    – Nifim
    Commented Jul 19, 2023 at 21:52

5 Answers 5

2

Programs are not dependent on byte count. Be descriptive. 30 years ago, people would have thought _srl() would be a great name for it, because set_relay(), oh the horror, how many bytes wasted on naming things.

What is wrong with SetPhysicalRelayToSetPosition()? It's literally how you explained what it is doing. It should be easy to understand for both audiences.

2
  • Your suggestion of SetPhysicalRelayToSetPosition() really opened me up to some other options I had not thought of, including the word position into the function name feels like it addresses niggling issue I was perceiving.
    – Nifim
    Commented Jul 19, 2023 at 18:56
  • The horror I've dealt with is systems that only allow 8 character names.
    – Peter M
    Commented Jul 19, 2023 at 21:40
3

This is a name collision. It’s a nasty one because the domain experts can’t help you because the collision isn’t happening in the domain. It’s happening in the convention you use to express the domain in code.

Therefore you need a new way to express the same idea to avoid confusion. Alternatives like setPhysicalRelay() have been suggested, and might be fine.

However, don’t trust. Check. Ask a domain expert who works with relays and one who works with code. Neither should be you. Find a name both understand.

Don’t be shy taking your time with this. Good names are worth fighting for.

1

We don't have to convey all possible meaning in one name.  It is not just about naming but also context & documentation.

In an OOP context, you would have something like a RelayController or RelayActuator class with perhaps instance methods set and reset — the class would be documented as to what it does, and perhaps also offer some information about how long relays take to engage, and whether the method returns success/failure or a promise that can be checked later.

For other context, you have the whole function signature to work with, not just the name of the function, and if you're lucky, a module containing the function(s).  Ideally, these functions (and/or modules) would also be documented, rather than expecting a consuming programmer to infer the operation from the name alone.

A more complicated relay controller might also offer methods to inspect the state of the relay, time of last operation (or history or error state), and might allow being coupled into a larger system of state & error handling.

So, use the context to help convey meaning (class/module, function signatures) — and also provide documentation!


How should one handle situation like this?

Seek to provide a larger context for the consuming programmers.  Yes, names are important, but we can do more.

What should the function be called?

In the right context, simple set and reset would be ok.

Am I over thinking it and SetRelay is fine?

That name doesn't convey to me what it actually does or should do.  In some sense, I think you're underthinking the larger context — so expand to a higher level point of view.

I need to know whether the function will wait to return with the relay positively set (e.g. is synchronous), or just the relay set command having been issued (e.g. is more async).  I need to know what happens if the relay won't set.  I need to know what happens if the relay was already set, and someone calls this method again.  Some of these things can be addressed with context (function signature, checked exceptions), others with documentation.  You want to provide an overall, well-thought out package, not just good method names.

0

I struggle to see the problem. As both an electrical engineer and programmer I would be totally at home with openRelay() and closeRelay() names for the methods that physically operate the relay.

0

You can have both the programmatic and domain-specific meaning align with the right name. "Set" on its own is too broad and can indeed be confused with the programming concept rather than the electrical one. Here are some alternatives (C#):

SetRelayState(currRelay, state: true);
currRelay.State = RelayState.Closed;
currRelay.State = prevRelay.State;
currRelay.SetPosition(Position.Open);
currRelay.CloseCircuit();
currRelay.OpenCircuit();
currRelay.Invert();
Energise(currRelay);   // These terms are relative to the NC/NO nature of
Deenergise(currRelay); // the relay, rather than absolute positions, if desirable.

// Finally, this can specify the goal (and implicitly the desired open/closed state)
// and can do a sanity check. Specifying a relay that would not switch on this
// device would throw an error.
upperHeatingElement.SwitchOnVia(backupPowerRelay);
1
  • I mentioned a bit in the question about why "connect" felt like a bad option similarly open and close fall into that bucket. In more detail the relays are single throw double pole latching relays, this means they have 2 connection and will always be connected to 1 of those connection and not the other. The manufacures of the relays often label these connections "set" and "reset" based on the which coil causes them to latch to that contact.
    – Nifim
    Commented Jul 21, 2023 at 14:13

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.