[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: weekly report for 2009-06-15~2009-06-20

From: C. Michael Pilato <cmpilato_at_collab.net>
Date: Mon, 22 Jun 2009 12:28:20 -0400

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

Received on 2009-06-22 18:28:42 CEST

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.