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.
Cheers,
-g
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
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2364236
Received on 2009-06-22 20:30:14 CEST