How to say 'must have' when this is not an opinion, but a certainty?

Question

I'm commenting a portion of a computer program. I would like to say that some portion of the code is reached after the user has pressed a button, and that he/she actually had no other option.

My initial phrasing was:

The user has clicked a button, let's update the message accordingly...

But I would like to emphasize the fact that the user was not given any other possibility than to click a button anyway. My tentative:

The user must have clicked a button.

But I fear must could weakens the assertion, and that the sentence might now means:

My opinion is the user has clicked a button.

Answer 1

When you use the modal verbs must or cannot, you are treating what follows as one possibility among many. Must means that all other possibilities are ruled out (impossible). Cannot means that the possibility is ruled out. Other modal verbs also treat what follows as a possibility, but I'll ignore them in this answer.

When you write without a modal verb of possibility, like The user clicked a button or The user has clicked a button, you are just saying what's happening or describing the state of things. Oddly enough, this expresses higher certainty than if you say must.*

In program comments:

• Must emphasizes that all other possibilities have been ruled out (or that a specification requires something, which the program code is ensuring).

• At this point emphasizes when the event occurs in the sequence of events.

• Have (present perfect tense) means that something happened earlier, but it's relevant to the line of code being executed now.

In program comments, a likely place where you'd say must is at the end of a chain of if-else-else clauses, because the previous clauses ruled out all other possibilities than the one you're assuming in the last clause. For example:

if (eventWord & 0x80) {  // did something happen?
  if (threadStatus & 0x04 == 0) {
    // we're being terminated
    . . .
  } else if (keyboardStatus != 0) {
    // the user hit a key
    . . .
  } else {
    // the user must have clicked a button
    . . .
  }
}

Since must means that other possibilities are excluded, it's especially appropriate to indicate that you're making an inference rather than straightforwardly observing or directly testing something.

In a statement about how things should be rather than an inference about how they are, must means that no other possibility is acceptable. For example, "Every secure transaction must be encrypted"; that is, sending it without encryption is unacceptable.

Regarding this: In situations that aren't so mathematically precise, people often use must have a little more loosely. It doesn't mean that other possibilities are proven not to have happened, it just means that the speaker considers the evidence or reasoning to have made other possibilities unlikely. For example, in "The bus passengers must have heard a crunch", obviously that wouldn't be true if the bus passengers were all deaf. But how likely is that? The example of "The car passengers must have escaped out the back" is especially relevant to the way one usually writes program comments, because there are only a few possible ways the passengers could have exited the bus, and the speaker is ruling out all but "out the back". In all of the examples, must have emphasizes that the speaker is making an inference, not a direct observation.

---

^{* This is only because once you start raising alternate possibilities, there is always some doubt, no matter how much certainty you claim to have. For example, if you really want to make someone doubt that you turned off the oven, just say "I am 100% certain that I turned off the oven."}

Answer 2

When writing comments in source code, I try to keep the statements simple, and I write in the tense that reflects the current point in the code as the present moment. I would write:

"The user has clicked ActionButton. Do Action and return 42 if successful."

On the other hand, is it important that the user clicked that button? Are you certain that will be their only option in the future if new features are added? In my opinion, it is better to document what your code expects to be true at a certain point. You might say what the button does instead of what the user does:

"The DoAction event has been triggered and myFlag is set."

It's clearer to talk about what must be true at a current point in the code instead of what must have happened before that point. The clearest construction is to state what must be true as a fact, but you could also say

"The button must be clicked before this function is called or it's curtains for the server."

Answer 3

If I understand your situation correctly, you want to document that a certain section of code will not behave correctly unless a button has been clicked.

One simple modal probably won't do the job.

If the code in question is the event handler, then there's nothing to document. I'm guessing that this isn't the situation at hand.

If the code only makes sense when it is called from the event handler, or if the language doesn't support explicit event handling, then you do have something to document. The kind of phrasing you used in one of your comments is both clear and natural:

• This line expects that a button was clicked.
• This line assumes a button was clicked.

Of course, the comment might apply to a block or a routine rather than a single line. You can pick whichever subject makes sense for the matrix clause. Alternately, since inline comments can employ an abbreviated conversational tone, you may be able to omit the subject entirely:

# assumes button was clicked:
label.text = optionlst[ button.value ]

Answer 4

If this were a question purely about english, I would think it should be

The user was forced to click a button

But I don't think that's a good description of what the program is doing.

I think it would be more helpful to say what the button is for rather than discuss the button itself.

On first reading I thought there was only one button, which I took to mean that the purpose of the button was to wait for the user to be ready to continue, which could be expressed with something like

Now that user is ready, proceed to ...

With more than one button, I assume the program is forcing the user to choose from some set of options (with one button per option), which could be expressed with something like

The user chose an option, let's update the message accordingly

As a matter of taste, I would prefer something like

Update message to reflect selected option

I think it's okay for the fact that the user was forced to click the button to be implied by the comments describing the code that displays the buttons, for example

Prompt the user to choose an option

If I read that comment, I would assume that the thread would not proceed until an option was chosen. Unless the comments indicate otherwise, I would also assume that one of the options is to abort (or cancel), so the user is not trapped.

If the user is trapped, a comment should explain why. Although I don't think it's necessary, it wouldn't hurt to explicitly mention that it can be aborted(/cancelled).

Since JOptionPane is modal, the user isn't just forced to chose an option to continue this thread, the user is prevented from interacting with the rest of the program until an option is chosen.

In my opinion this is bad design, and if I were commenting this code my comments would reflect that opinion. How appropriate that is may depend on who is expected to read these comments. In any case I think it's important to accurately describe the effect, for example

Prompt the user to choose an option (and don't let them do anything else until they do)

or

Block the user from any other action until they choose an option

(Of course, the user always has other options, such as killing the program or unplugging the computer, but it would be overkill to mention those.)