0

I've been arguing with a colleague about a description for a piece of code. Originally, the message was as follows:

XXX is a macro that, given a component name and a variable name pattern, produces a name of a component-specific variable.

But my colleague thinks that the following would sound better:

XXX is a macro that for the given component name and variable name pattern produces a name of a component-specific variable.

My main question is: is the phrase "for the given component name ..." allowed at that position (i.e. before the verb)? I have the feeling that such phrase is only possible after the object (i.e. "... produces a name of a component-specific variable for the given component name ...") but I've been unable to find any specific rule. Also, what is the correct grammatical term for the phrase? (Is it an adjunct?).

Finally, if both sentences are possible, which of them sounds better?

3
  • Given a component name and a variable name pattern, XXX is a macro that produces a name of a component-specific variable.
    – Smock
    Jun 20 '19 at 13:43
  • @Smock Sorry, for the later reply, I don't seem to get email notifications from stackexchange. I don't think that your suggestion will work. In the original variants, the meaning is that 1) XXX is a macro; 2) given something, it produces something else. And your variant seems to suggest that XXX is a macro only when it is given something. Or may be I'm missing something?
    – ohforf
    Jun 26 '19 at 15:37
  • Both are acceptable and fine but could be simplified by breaking the sentence sentence down into smaller concepts. e.g. “XXX is a macro. It produces the name of a context specific variable. The variable name produced depends on the supplied component and variable name pattern.”
    – jwpfox
    Nov 29 '20 at 19:53
0

This one is a little tricky. Your second example reads slightly better to me, as it flows almost continuously. On the other hand, in a slightly longer example of this sort of thing, the frequent use of (correct) punctuation can help to make things much clearer.

Neither example is horrible, but I would write this something like: "XXX is a macro that produces a name of a component-specific variable, given a component name and a variable name pattern."

(In reality, I would probably make it slightly more verbose, but maybe not for the better!)

This site is temporarily in read only mode and not accepting new answers.

Not the answer you're looking for? Browse other questions tagged .