FreeTDS Development Group

["Lowden, James K" <LowdenJK AT bernstein.com>]

Does anyone else get confused by inconsistent naming conventions in libtds?

(what is he talking about?)

Some are very nice and easy to grasp.  

TDSLOGIN *tds_alloc_login(void)
TDSCONTEXT *tds_alloc_context(void)
TDSSOCKET *tds_alloc_socket(TDSCONTEXT *context, int bufsize)
TDSDYNAMIC *tds_alloc_dynamic(TDSSOCKET *tds, const char *id)

I need a TDSLOGIN*, so I call tds_alloc_login(); I see a call to
tds_alloc_login(), and I expect a pointer to a TDSLOGIN structure to be
returned.  

Some use "info" a little gratuitously:

TDSCONNECTINFO *tds_alloc_connect(TDSLOCINFO *locale)
TDSENVINFO *tds_alloc_env(TDSSOCKET *tds)
TDSRESULTINFO *tds_alloc_results(int num_cols)

Two whose names and types are not well matched:

TDSLOCINFO *tds_alloc_locale(void)
TDSPARAMINFO *tds_alloc_param_result(TDSPARAMINFO *old_param)

Here are three I'd say are ill-defined:

void *tds_alloc_compute_row(TDSCOMPUTEINFO *res_info)
void *tds_alloc_row(TDSRESULTINFO *res_info)
unsigned char *tds_alloc_param_row(TDSPARAMINFO *info,TDSCOLINFO *curparam)

Two that are very confusing:

TDSCOMPUTEINFO **tds_alloc_compute_results(TDS_INT *num_comp_results,
TDSCOMPUTEINFO** ci, int num_cols, int by_cols)
TDSCOMPUTEINFO *tds_alloc_compute_result(int num_cols, int by_cols)

+++

Only slowly (me being me) have I grasped that a column is described by
TDSCOLINFO, while many columns are TDSRESULTINFO, or identical typedefs:
TDSPARAMINFO and TDSCOMPUTEINFO.  

Doxygen looms.  Rather than documenting this hodgepodge in situ, I propose
to revise it, wholesale, as follows:

1.  Strike "INFO" from every typename and use a word instead, if possible.
s/TDSCONNECTINFO/TDSCONNECTION/; s/TDSLOCINFO/TDSLOCALE/;
s/TDSCOLINFO/TDSCOLUMN/.  Et cetera.  

2.  Since TDSRESULTINFO, TDSPARAMINFO, and TDSCOMPUTEINFO are all the same
thing, let's use one name.  I offer TDSRESULTDESC or TDSCOLUMNS.  Or just
leave it TDSRESULTINFO.  

3.  Name the allocation routines after their types, unless the same type is
allocated by several routines, e.g.:
        TDSCONNECTINFO *tds_alloc_connect(TDSLOCINFO *locale)
        becomes
        TDSCONNECTION *tds_alloc_connection(TDSLOCALE *locale)

I don't think these changes will improve run-time or compile-time
performance, but think-time should get much better.  

Comments solicited, as ever.  

--jkl



The information contained in this transmission may contain privileged and
confidential information and is intended only for the use of the person(s)
named above.  If you are not the intended recipient, or an employee or agent
responsible for delivering this message to the intended recipient, any
review, dissemination, distribution or duplication of this communication is
strictly prohibited. If you are not the intended recipient, please contact
the sender immediately by reply e-mail and destroy all copies of the
original message. Please note that we do not accept account orders and/or
instructions by e-mail, and therefore will not be responsible for carrying
out such orders and/or instructions.