Stefan Sperling wrote:
> Why is svn_client_collect_commit_packet() public?
>
> Making the function public means that it can be called from outside
> of libsvn_client. I don't think we need it to be public. It's enough
> to have the public function svn_client_commit4(), isn't it?
>
> I think svn_client_collect_commit_packet can be local to the file
> it is being used in (i.e. call it just collect_commit_packet and
> mark the function as static).
Huihuang, if I may, I'd like to expand on this just a bit for your sake and
the sake of others who might be reading.
Subversion's code and headers files are segregated along a couple of key
lines: module-specific/inter-module and public/private. This separation is
done primarily because of our focus on proper modularity and code
organization, but also because of our promises as providers and maintainers
of a widely adopted public API. As you write new functions in Subversion,
you'll need to carefully consider these things, asking some questions of
yourself as you go along:
"Are the consumers of my new code local to a particular source code file
in a single module?" If so, you probably want a static function
in that same source file.
"Is my new function of the sort that other source code within this
module will need to use, but nothing *outside* the module?" If so,
you want to use a non-static, double-underscore-named function (such
as svn_wc__do_something), with its prototype in the appropriate
module-specific header file.
"Will my code need to be accessed from a different module?" Here you
have some additional questions to answer, such as "Should my code
live in the original module I was going to put it in, or should it
live in a more generic utility library such as libsvn_subr?" Either
way, you're now looking at using an inter-module header file. But
see the next question before you decide which one...
"Is my code such that it has a clean, maintainable API that can
reasonably be maintained in perpetuity and brings value to the
Subversion public API offering?" If so, you'll be adding
prototypes to the public API, immediately inside subversion/include/.
If not, double-check your plans -- maybe you haven't chosen the best
way to abstract your functionality. But sometimes it just happens
that modules need to share some function that is arguably of no use
to other software besides Subversion itself. In those cases, use
the private header files in subversion/include/private/.
I hope this helps. (And better still, I hope I've provided something that
the other devs would agree with. If so, maybe we can toss this text into
hacking.html for the benefit of future others.)
--
C. Michael Pilato <cmpilato_at_collab.net>
CollabNet <> www.collab.net <> Distributed Development On Demand
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2364212
Received on 2009-06-22 18:28:42 CEST