tech-writing geeking

[cellio]

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

Comments

[geekosaur]

Your code is getting a value by calling the method, but the method does not "get", it "returns" or "provides access to".

Sadly, that's fighting an uphill battle against pretty much every C++ book and C++ instructor I've ever seen or heard of; students are regularly abjured to name the accessor for foo getFoo, and code generators from the GPLed Glade to IBM's VisualAge product line follow the same convention.

[tangerinpenguin.livejournal.com]

Likewise the Java world; I think getFoo() (often with the addition of isFoo() for predicates) and setFoo() have become so well-known that you may be losing more immediate comprehension by defying the convention than you gain by more strictly expressive language.

[tangerinpenguin.livejournal.com]

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.

In what cases is this more true for a specific method, rather than being something derived from the class or the context? In general, I see a danger here of tying the interface too much to the implementation - given subsequent changes "under the hood", a computation that initially seemed heavy-weight might become trivial, or vice versa, but at that point it's been enshrined into a method name that's distributed throughout existing code.

In practice, I tend to get the same semantic value from the context provided by the class: I assume that getFoo() (or returnFoo() :-)) on classes in the DB layer are going to be doing some sort of database hit (possibly optimizing through caching somehow), that the same call on an EJB has attendant RMI overhead, the same call on a value object or simple databean is (probably) pulling it off a local attribute, and the same call on a Business Object may be fronting any of the above (this week...) and my business logic is the wrong place to be worried about it.

And, further, that there are maintainence advantages to having all of the above implement (under Java or the like) one interface that specifies the same data contract crossing the physical layers of the application.

[cellio]

Perhaps strangely, I don't have a problem with the accessor being named "getFoo" -- but I do have a problem with the documentation saying "gets a foo" (for reasons other than redundancy, I mean). With the documentation we have the flexibility to be very, very clear; with the actual method name, other factors such as ease of typing and existing conventions come into play more. (There are doc conventions too, of course, but if you browse random C++ or Java API docs you'll probably see "returns" more than "gets" in that text.)

[cellio]

The method should be named for the most general state that might be true -- so if we're only promising that you'll get a value it should be "getFoo" (documented as "returns a Foo that..." :-) ). If, on the other hand, you intend to say "hey, I'm going to do a server round-trip here instead of fetching the client's local copy", I'd suggest that a name like "fetchFoo" or the like would be better.

I didn't mean to turn this into a discussion of method naming, but that's ok. (Outside of the realm of most tech writers, though.) There are lots of factors that affect method naming, as opposed to method documentation, and I didn't mean to pick out only one for excess attention.

Ah...

[tangerinpenguin.livejournal.com]

OK, "my bad" not reading it correctly (can you tell I've been working a lot this week with "principles of API design" and "layered architectures" and "developing to the interface"? :-)). Yes, I can fall in behind this point much more easily: if there are any interesting constraints posed by the implementation, they need to be documented for the class where they're implemented.

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

[cellio]

can you tell I've been working a lot this week with...

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.