0

I often uses the verb provide for describing interfaces between components. For example:

The interface IMath provides the common math functions for (...).

I don't want to use the same verb every time.

Does the usage sound natural to native speakers and are there alternatives to describe it?

  • "The interface IMath introduces the common math functions..." could be another alternative. – James Sep 23 '15 at 12:36
  • I don't want to use the same verb every time. But for documentation you shouldn't, you wouldn't want to confuse your readers into thinking that there's a difference between providing, defining, specifying etc. – curiousdannii Sep 23 '15 at 13:19
4

Generally speaking I believe that the richness of the English language should be used at every opportunity. If you use the same expression over and over again, it becomes potboiler writing. Boring. Unimaginative. Tedious.

There is a "but" here. And that "but" is technical documentation, which I believe is more effective if the writer maintains a uniform style of description. The reason is that the reader then doesn't have to guess whether the writer was using some form of nuance in their description of the code. If you're describing an Interface, and always use the same terms, then the reader knows exactly what you are saying and doesn't have to guess whether you might have been implying a difference between this Interface and that Interface because a different term was used to describe it.

All that having been said, I would suggest one change to what you're writing. (And I realise that this is well outside the ELU group's usual purview.) As you doubtless well know, an Interface does not in itself "provide" functionality (in the sense of implementing that functionality in a usable form), any more than the blueprint of a house can be said to provide the house. It's part of the process of providing the house, true; but it does not itself provide it. It merely defines the base level of functionality that a class which implements the Interface must provide. I would therefore be more inclined to write:

"The Interface IMath defines the common math functions for..."

or perhaps

"The Interface IMath specifies the common math functions for..."

There are probably some other words that you could use instead of defines or specifies, and I'll readily admit that anyone who knows what an Interface is won't be actually misled by the word "provides" in this context... but in my humble opinion it's not a technically accurate definition of what it's doing.

Though I'm well aware that others may have differing opinions on that point.

  • You're right that an interface only specifies the methods. I used the word provide because for the counterpart component it's some kind of "offer". Following your argument I have the choice between the verbs define and specify. – Bjoern Sep 23 '15 at 9:31
  • @Bjoern Go with "define." It's the correct word to describe programming functions. "Specify" would be better suited to explaining parameters. – VampDuc Sep 23 '15 at 18:06
3

If you are writing documentation for a software library, then your concerns about repetition of the verb are unnecessary. People do not read software documentation like they read a novel. They don't care about flow or maintaining reader interest. They are much more interested in exactness of meaning.

If you use a different verb to mean the same thing in different interfaces, they may start to worry that there is some subtle difference between the two interfaces because you use a different verb. If you use the same verb, and the same writing pattern, for each interface then readers will find it easier to read because they start to pick up the pattern and can digest it faster. Unnecessary changes in the pattern will slow them down.

TLDR: In technical writing, consistency is a plus, not a minus.

0

Another way can be "The Interface IMath supports the common math functions for...".

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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