tech-writing geeking
Jul. 22nd, 2003 01:36 pm![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
cellioOne of these years I may make a real effort to compile some of what I do into the beginnings of "Tech-Writing Pearls", but for now all I'm doing is stashing stuff away when I realize I've written something that could be fodder later. Like now. :-)
On an API-documentation list someone asked about verb choice for access methods -- "returns", "gets", "retrieves", "queries", and so on.
I strive to be very careful to expose the correct amount of implementation in the documentation. That is, sometimes we only want to promise that we return a value somehow. Other times, we want to convey to the user that a new computation (e.g. a database query) is happening, which should affect the conditions under which he calls the method. So, using a word that implies computation when we're promising not to compute actually makes things worse.
I use "returns" almost universally. If we're actually computing or fetching a value, and this behavior is part of the interface specification, I'll say that, but I'll also try to get the programmers to name the method something other than "getFoo" in that case, too.
I view the method itself as the subject of the sentence, so I dislike "gets" because that's not what the method does. Your code is getting a value by calling the method, but the method does not "get", it "returns" or "provides access to". This may seem like excessive anal-retentiveness, but there can be cases elsewhere in an interface where it is not at all clear where the work gets done, and I find that if I am stubbornly consistent about using verbs that apply to the method (rather than the caller), I can reduce the potential for confusion elsewhere. My readers can learn the pattern if there is a pattern.
Update: I intended to focus here on what to say in the documentation, and not how to design the API, but I probably didn't make that clear enough before. Sorry 'bout that.
On an API-documentation list someone asked about verb choice for access methods -- "returns", "gets", "retrieves", "queries", and so on.
I strive to be very careful to expose the correct amount of implementation in the documentation. That is, sometimes we only want to promise that we return a value somehow. Other times, we want to convey to the user that a new computation (e.g. a database query) is happening, which should affect the conditions under which he calls the method. So, using a word that implies computation when we're promising not to compute actually makes things worse.
I use "returns" almost universally. If we're actually computing or fetching a value, and this behavior is part of the interface specification, I'll say that, but I'll also try to get the programmers to name the method something other than "getFoo" in that case, too.
I view the method itself as the subject of the sentence, so I dislike "gets" because that's not what the method does. Your code is getting a value by calling the method, but the method does not "get", it "returns" or "provides access to". This may seem like excessive anal-retentiveness, but there can be cases elsewhere in an interface where it is not at all clear where the work gets done, and I find that if I am stubbornly consistent about using verbs that apply to the method (rather than the caller), I can reduce the potential for confusion elsewhere. My readers can learn the pattern if there is a pattern.
Update: I intended to focus here on what to say in the documentation, and not how to design the API, but I probably didn't make that clear enough before. Sorry 'bout that.
(no subject)
Date: 2003-07-22 01:52 pm (UTC)Ah...
Date: 2003-07-22 02:11 pm (UTC)As a bonus, automation works for you in the case of "get" versus "return" - Javadoc documents the return value for everything using "return" (although you ought to explicitly use the @return tag to give a useful description rather than just letting it say "returns something of type long")
Re: Ah...
Date: 2003-07-22 03:03 pm (UTC)Never would have guessed. :-)
Automation also works for you, when using Javadoc, in propegating a description downward until overridden. Some developers don't know this, and methodically cut and paste the documentation of a method from the interface to the implementing class, thereby making more work for everyone involved. I've been trying to spread the convention in my company of "// inherited javadoc ok" before methods for which that's true. That tells readers of the code that you considered and rejected new javadoc, rather than that you never got around to dealing with it.