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

Re: svn commit: r38143 - trunk/www

From: Greg Stein <gstein_at_gmail.com>
Date: Mon, 22 Jun 2009 20:29:57 +0200

Why the term "module" instead of "library"? We never use the former,
and the directories are named lib*. Using "module" doesn't seem to add
any clarity, and definitely can confuse. Halfway through, I realized
"module" meant "library" rather than one source file.


On Mon, Jun 22, 2009 at 20:19, C. Michael Pilato <cmpilato_at_collab.net> wrote:
> Author: cmpilato
> Date: Mon Jun 22 11:19:04 2009
> New Revision: 38143
> Log:
> * www/hacking.html
>  Add a section about interface visibility.
> Modified:
>   trunk/www/hacking.html
> Modified: trunk/www/hacking.html
> URL: http://svn.collab.net/viewvc/svn/trunk/www/hacking.html?pathrev=38143&r1=38142&r2=38143
> ==============================================================================
> --- trunk/www/hacking.html      Mon Jun 22 10:56:46 2009        (r38142)
> +++ trunk/www/hacking.html      Mon Jun 22 11:19:04 2009        (r38143)
> @@ -38,6 +38,7 @@ $LastChangedDate$
>  <li>Theory and documentation</li>
>  <li>Code to read</li>
>  <li>Directory layout</li>
> +<li>Code modularity and interface visibility</li>
>  <li>Coding style</li>
>  <li>Secure coding guidelines</li>
>  <li>Destruction of stacked resources</li>
> @@ -343,6 +344,47 @@ to ask for review on the developer maili
>  </div>
> +<div class="h2" id="interface-visibility" title="interface-visibility">
> +<h2>Code modularity and interface visibility</h2>
> +
> +<p>Subversion's code and headers files are segregated along a couple
> +of key lines: module-specific vs. inter-module; public vs. 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:</p>
> +
> +<p><em>"Are the consumers of my new code local to a particular source
> +code file in a single module?"</em>  If so, you probably want a static
> +function in that same source file.</p>
> +
> +<p><em>"Is my new function of the sort that other source code within
> +this module will need to use, but nothing *outside* the module?"</em>
> +If so, you want to use a non-static, double-underscore-named function
> +(such as <tt>svn_foo__do_something</tt>), with its prototype in the
> +appropriate module-specific header file.</p>
> +
> +<p><em>"Will my code need to be accessed from a different
> +module?"</em>  Here you have some additional questions to answer, such
> +as <em>"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?"</em>  Either way, you're now looking at using an
> +inter-module header file.  But see the next question before you decide
> +which one...</p>
> +
> +<p><em>"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?"</em>  If so, you'll be adding
> +prototypes to the public API, immediately
> +inside <tt>subversion/include/</tt>.  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 <tt>subversion/include/private/</tt>.</p>
> +
> +</div>
>  <div class="h2" id="coding-style" title="coding-style">
>  <h2>Coding style</h2>
> ------------------------------------------------------
> http://subversion.tigris.org/ds/viewMessage.do?dsForumId=495&dsMessageId=2364233

Received on 2009-06-22 20:30:14 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.