Nit pick -- where to stick the * in a C/C++ definition
I am documenting an API in C++. I need to decide on a
standard representation for pointer definitions.
C and C++ themselves don't care whether I say:
int * foo //centered
int* foo //closed left
or int *foo //closed right
I had decided to go with the "closed left" form,
and was chatting with a developer. He agreed that
it was typical, but reminded me that if one opts
to define multiple pointers on one line, the asterisk
must precede each name. If one writes
int* foo, bar
one has defined a pointer-to-integer named foo and
an integer named bar. To get both to be pointers,
one must put an asterisk before each -- in which
case, it looks better to use "closed right" form:
int *foo, *bar
Now, my document is going to have one definition per line
in the explanations. There is a chance that examples
would include compound definitions, solely in the interest
of saving vertical space.
What is the collective wisdom on positioning the asterisk
in API documentation?
First of all, when displaying code, my primary interest is NEVER in saving vertical space, although I agree that it's nice to get a whole "chunk" together on each page.
I do try to get whole statements together across the width of the page, but since that is often impossible, I settle for formatting it so it' as readable as possible. So, for example, my preference is to put spaces before and after an equal sign, but, if by removing those spaces I can keep the entire statement together on one line, I usually choose to remove the spaces.
I try to be very certain that every variable in the code I display is there for a reason. Therefore, I prefer the following format:
1. Every variable on its own line, with a comment near it that explains what the variable does; or if the types and/or variables and/or explanation is very long, I put the comment on its own line before the definition.
2. Each variable listed in alphabetical order so reader can find it (a trick I learned from a programmer ages and ages ago and which I use in my own code as well);
3. List function definitions separately from variable definitions, in alphabetical order by function name.
4. Type <tab (enough so all variable names line up)> * or & or whatever <tab again> variable name. (I think the * or the & should be significantly closer to the variable name than to the datatype; so my vote would be for closed right or actually, slightly off-centered but closer to the right.)
So a variable list might look like this:
/* Variable Definitions */
int <2 tabs here> theIntThatIsNotAPointer, /* this int does blah... */
<tab here>*<short tab here>thisIsAPtrToAnInt; /* this ptr is used ... */
/* The thisFunctionReturnsAnInt() function does blah */
int <2 tabs here> thisFunctionReturnsAnInt();
/* Function Definitions */
/* The thisFunctionReturnsAPtrToInt function does blah */
int <Tab here>*<Small tab here>thisFunctionReturnsAPtrToInt();
Well, anyway, that's what I do.
On the web at www.armadillosoft.com *** Armadillo Associates, Inc.
~ Project management, developer relations and
extremely-technical technical documentation that developers find useful.~
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**New Dates!!** San Francisco (Apr 16-17), San Jose (Mar 29-30)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. http://ieeepcs.org/2001/
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
Previous by Author:
SN Not Valid: A Non-Fiction Novella Chapter 2 by Emily Berk
Next by Author: SN Not Valid: A Non-Fiction Novella; Epilogue by Emily Berk
Previous by Thread: RE: Nit pick -- where to stick the * in a C/C++ definition
Next by Thread: Nit pick -- where to stick the * in a C/C++ definition
Search our Technical Writing Archives & Magazine