TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
My client's product provides multiple client interfaces: C++, COM (ASP and
Visual Basic), and Java. I'm working on a programming manual that is 98%
common for all four interfaces, with FrameMaker conditional text variants
for language-specific code snippets and warnings.
I realize now that not everyone agrees on what the non-method data
referenced within an object should be called. There are several choices, and
some might be language specific biases:
"Field" -- from my Java 2 Black Book manual
"Property" -- from my Visual Basic manual
"Value" -- I've seen other places
"Variable" - some C++ programmers would say this
"Attribute" -- in an abstract object-oriented design web page I saw
Which is best? That's not it yet! It gets trickier...
The COM interface has a dramatically different implementation from Java and
C++. If there is a "Foo" field/property/value within an object, the C++ and
Java versions use Get/Set methods; the COM version modifies them directly --
or appears to from within ASP and Visual Basic, the only COM environments
supported.
Because 98% of the text is in common for all languages and we have limited
time, it's not feasible to use both paradigms (Get/Set versus just
reading/writing the object value). I'm documenting the Foo field as a
field/property/value, not as a twin pair of Get/Set methods. That's my call
for now. I realize some of you might feel differently, but that is NOT what
I'm asking about.
In some sense I'm referring to actual properties/fields of the object. And
in COM, it seems exactly like that for developers. But in C++ and Java, it's
really mentioning undocumented protected/internal variables and then says at
the beginning how to use Get/Set methods, which some might say means that
the text in the manual is necessarily an abstraction anyway and hence
language-specific text is NOT a requirement.
What I am asking is: what do I call data properties within an object in a
situation like this? Properties? Fields? Values? Variables? Attributes?
Examples in context: (note that Courier is used as appropriate...)
You must set its Length and Width fields before calling its Go method.
You must set its Length and Width properties before calling its Go method.
You must set its Length and Width values before calling its Go method.
You must set its Length and Width variables before calling its Go method.
You must set its Length and Width attributes before calling its Go method.
Thoughts? Please provide *reasons*, not just language-specific history like
that's what your C++ teacher told you it was called in C++. :-)
