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

6

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.

mins

Posted 2014-12-13T12:18:28.770

Reputation: 349

You would not use "my opinion" for a fact. Would you tell us more about what you're trying to write? Are you explaining the user interface design? – ColleenV – 2014-12-13T12:32:49.477

1@ColleenV: I'm commenting a program. I want to describe the conditions for executing an instruction (the instruction can be reached only if the user clicked a button). – mins – 2014-12-13T12:35:02.773

2By the way, one rule of thumb I use when writing comments is "don't state the obvious". – Damkerng T. – 2014-12-13T20:01:42.663

Answers

5

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."

Ben Kovitz

Posted 2014-12-13T12:18:28.770

Reputation: 25 752

4

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."

ColleenV

Posted 2014-12-13T12:18:28.770

Reputation: 11 270

Why not say "this value can't be null"? Currently the button may be the only way for that value to be set, but in the future, maybe the program will respond to voice commands or something. Unless of course you are working with an API that is unlikely to change. @mins – ColleenV – 2014-12-13T13:12:14.723

Sure, this is ok to add information in the current case. However my initial question was purely for improving my English vocabulary, and understanding if there was some modal verb to express a certainty. – mins – 2014-12-13T13:21:31.860

3@mins Oddly enough, a total lack of modal verbs indicates certainty, as in ColleenV's examples. In program comments, you might write must or cannot to indicate the conclusion of a deduction: "Such-and-such was called, so X cannot be null." – Ben Kovitz – 2014-12-13T13:29:22.813

@mins This might be the right way to think of it: when you say must or can, you are treating what follows as a possibility. Must means that you are ruling out all other possibilities. Omitting the modal verb means that you're just saying what is happening, not contrasting it with alternatives. – Ben Kovitz – 2014-12-13T13:33:36.260

@BenKovitz: No sure I understand everything. If I say At this point a button must have been clicked, so..., does it means other possibilities (no button clicked) have been ruled out (like in the affirmative form: You must click one of the buttons)? FYI, I'm trying to get this.

– mins – 2014-12-13T13:42:42.257

1@mins Yes. When you say At this point, a button must have been clicked, so… that means that you are ruling out the possibility that no button was clicked. When you say A button was clicked, so… that just means that a button was clicked. It's really the same thing, just a difference of emphasis. – Ben Kovitz – 2014-12-13T13:59:48.607

1@mins You would probably use the must phrasing at the end of a series of if-else-else-… statements, because the previous if and else clauses have ruled out other possibilities than the current else clause. – Ben Kovitz – 2014-12-13T14:01:39.387

@mins Also, when you say At this point… you are emphasizing when the button-click occurs in the sequence of events. If you just say A button has been clicked… you are emphasizing the fact that the button-click is waiting to be attended to (or in other words, that the event is past but it's still relevant to the present action of the program). – Ben Kovitz – 2014-12-13T14:10:23.837

@mins Thanks for the suggestion! I'll write one up. It's still probably best to wait 24 hours before accepting an answer. Someone else might hit on an even better way to look at this. – Ben Kovitz – 2014-12-13T14:39:28.170

2

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 ]

Gary Botnovcan

Posted 2014-12-13T12:18:28.770

Reputation: 12 044

Thanks Gary. It seems many posters in the site are also programmers! So let's have the full context of the comment... I'll add it to my question. – mins – 2014-12-13T16:49:03.907

As a native speaker of American English, I'll let my original answer stand. My suggestion accomplishes something that a modal auxiliary can't. As a programmer, even though I barely speak Java, I don't see the reason for either of the comment lines in your sample code. The English comments tell me nothing that the Java code doesn't already tell me. By the way, this code assumes that everything except YES_OPTION means no, so I hope that OK_OPTION and nonstandard options don't appear in the dialog box. – Gary Botnovcan – 2014-12-13T18:21:51.363

1

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.)

ShadSterling

Posted 2014-12-13T12:18:28.770

Reputation: 111