Re: Verb Usage: "Returns"

Subject: Re: Verb Usage: "Returns"
From: Ben Kovitz <apteryx -at- CHISP -dot- NET>
Date: Wed, 9 Dec 1998 18:30:01 -0700

John David Hickey asked:

>I'm updating a programming guide and I'm having a hard time over a verb that
>keeps turning up. Maybe I can get a second opinion...
>
>The GET command returns the value of the variable as a string.
>
>What this command does is it goes to another part of the program, retrieves
>the value, and uses it in the current function. I replaced "returns" with
>"retrieves", but the reviewer didn't like it.
>
>I'd rather use "retrieves" because it shows how the program goes to a
>destination and returns with information. I don't like "returns" because
>only indicates the journey back.
>
>Is "returns" an industry standard (check out Dilbert today at
>www.dilbert.com for a related funny) in the programming world, or can I push
>for the more accurate verb?

"Returns", in the community that you're writing for, means something very
specific. It does not mean what you want to say. It means what needs to
be said, which is what the programmer wrote.

This sense of the word comes from mathematics. In mathematics, a
"function" is a type of mapping between sets. A function is a rule
relating elements taken from one or more sets to a single element from
another set. That single element is typically a number, and you can use it
in expressions just like any other variable or number. For example, f(2,
4) + f(8, 8) is simply the sum of the numbers that function f "returns",
given inputs of (2, 4) and (8, 8). Now you can see the original need for a
verb here. Without a verb, and not just a noun like "result", talking
about these numbers that functions, er, "return", would be quite a nuisance.

Now, in programs, different parts of a program are continually sending
information back and forth to each other. Subroutine A yields control of
the CPU in order for subroutine B to retrieve or calculate some
value--known as "calling" subroutine B. Subroutine B sends this value back
to subroutine A when subroutine B finishes. Is this starting to sound
familiar? "Returning" in programming is the act of one subroutine--also
sometimes called a "function"--giving a number or other value back to a
subroutine that called it.

The similarity is even stronger when you consider that typical programming
languages have notations copied somewhat from mathematics. In particular,
you can say things like GETN(stdin) + GETN(stdin) to mean, "call the GETN
subroutine twice, have it retrieve a number from stdin each time, and sum
those numbers."

I'm going very, very fast here, but I hope this at least gives you a
general idea, and maybe some questions to ask the programmers. There is a
whole network of concepts here, and if you aren't familiar with them, you
won't know what "returns" means to programmers. But in that network of
words and ideas, "returns" means something very specific, not to be
confused with "retrieves". And what it means is very difficult to explain
to someone who isn't familiar with that whole conceptual world.


I think this is a good example of just how much is involved in the
nearly-always-neglected-but-of-highest-importance part of technical
writing: learning the concepts and terminology of the audience. I spend a
long time doing this before criticizing the words they're using. (*Then* I
criticize.) I think a good rule is to always understand the rationale, or
you could say the etymology, of each new term: what is was extended or
varied from, how the concept relates to others in the field, and why people
found it helpful to invent or borrow a word to mean that. If you don't
know those things, you aren't yet in a position to criticize the usage.

I bring this up because this is such a common phenomenon: tech writer or
copy editor knows "the rules" but doesn't know the speech community; tech
writer or copy editor proceeds to impose "the rules" onto the text,
undermining its credibility in that community and making the document less
clear and less useful to its readers.

I'm not saying you're doing that, since, after all, you're asking rather
than imposing. However, it's a little out of the spirit of "specific
subject matter takes precedence over generalized rules" to be asking tech
writers and not subject-matter experts. The only reason that I knew the
answer was because I worked as a programmer for twelve years, not because
I'm a tech writer.


By the way, if you want a word that programmers write all the time but *is*
almost always better replaced by a more-precise word, it's "use".

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author, _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: Inserting Page Nos. in Word
Next by Author: The First Two Questions (Was: Design Document)
Previous by Thread: Help with ForeHelp, Please - Emergency!
Next by Thread: Word 97 problem solved


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads