<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'>
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Style Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="next" href="cvs-guidelines.html" title="CVS Guidelines"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="style-guide"></a>OpenACS Style Guide</h2></div></div></div>
  

  <p>
    By Jeff Davis
  </p>

  <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-motivation"></a>Motivation</h3></div></div></div>
    
    <p>
      Why have coding standards for OpenACS?  And if the code works why change it to
      adhere to some arbitrary rules?
    </p>
    <p>
      Well, first lets consider the OpenACS code base (all this as of
      December 2003 and including dotLRN).  There are about 390,000
      lines of Tcl code, about 460,000 lines of sql (in datamodel
      scripts and .xql files), about 80,000 lines of markup in .adp
      files, and about 100,000 lines of documentation.  All told, just
      about a million lines of "stuff".  In terms of logical units
      there are about 160 packages, 800 tables, 2,000 stored
      procedures, about 2,000 functional pages, and about 3,200 Tcl
      procedures.
    </p>
    <p>
      When confronted by this much complexity it's important to be
      able to make sense of it without having to wade through it all.
      Things should be coherent, things should be named predictably
      and behave like you would expect, and your guess about what
      something is called or where it is should be right more often
      than not because the code follows the rules.
    </p>
    <p>
      Unfortunately, like any large software project written 
      over a long period by a lot of different people, OpenACS 
      sometimes lacks this basic guessability and in the interest 
      of bringing it into line we have advanced these guidelines.
    </p>
  </div>

  <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-commandments"></a>Commandments</h3></div></div></div>
    
    
    <p>
      Here is a short list of the basic rules code contributed to 
      OpenACS should follow...
    </p>
    <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
        <p>
          <b>Follow the file naming and the package structure rules. </b>
          
            Some of the file naming rules are requirements for things
            to function correctly (for example data model creation
            scripts and Tcl library files must be named properly to be
            used), while some are suggestions (the
            <span class="emphasis"><em>object-verb</em></span> naming convention) which
            if ignored won't break anything, but if you follow the
            rules people will be able to understand your package much
            more easily.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Be literate in your programming. </b>
          
            Use ad_proc, ad_library, and ad_page_contract to provide
            documentation for your code, use comments on your
            datamodel, explain what things mean and how they should
            work.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Test. </b>
          
            Write test cases for your API and data model; test
            negative cases as well as positive; document your tests.
            Provide tests for bugs which are not yet fixed. Test,
            Test, Test.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Use namespaces. </b>
          
            For new packages choose a namespace and place all procedures in it
            and in oracle create packages.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Follow the constraint naming and the PL/SQL and PL/pgSQL rules. </b>
          
            Naming constraints is important for upgradability and for consistency.  Also, 
            named constraints can be immensely helpful in developing good error handling.
            Following the PL/SQL and PL/pgSQL rules ensure that the procedures created 
            can be handled similarly across both Oracle and PostgreSQL databases.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Follow the code formatting guidelines. </b>
          
            The code base is very large and if things are formatted
            consistently it is easier to read.  Also, if it conforms
            to the standard it won't be reformatted (which can mask
            the change history and making tracking down bugs much
            harder).  Using spaces rather than tabs makes patches
            easier to read and manage and does not force other
            programmers to decipher what tab settings you had in place
            in your editor.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Use the standard APIs. </b>
          
            Don't reinvent the wheel.  Prefer extending an existing
            core API to creating your own.  If something in the core
            does not meet your particular needs it probably won't meet
            others as well and fleshing out the core API's makes the
            toolkit more useful for everyone and more easily extended.
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Make sure your datamodel create/drop scripts work. </b>
          
            Break the table creation out from the package/stored
            procedure creation and use <code class="computeroutput">create or
            replace</code> where possible so that scripts
            can be sourced more than once.  Make sure your drop script
            works if data has been inserted (and permissioned and
            notifications have been attached etc).
          
        </p>
      </li><li class="listitem">
        <p>
          <b>Practice CVS/Bug Tracker Hygiene. </b>
          
            Commit your work. commit with sensible messages and include
            patch and bug numbers in your commit messages.
          
        </p>
        <p>
          Create bug tracker tickets for things you are going to work
          on yourself (just in case you don't get to it and to act as
          a pointer for others who might encounter the same problem).
        </p>
      </li><li class="listitem">
        <p>
          <b>Solicit code reviews. </b>
          
            Ask others to look over your code and provide feedback and do 
            the same for others.  
          
        </p>
      </li></ol></div>
  </div>

  
  <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-rev-history"></a>Revision History</h3></div></div></div>
    

    <div class="informaltable">
      <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.1</td><td>Creation</td><td>12/2003</td><td>Jeff Davis</td></tr></tbody></table>
    </div>
    <p><span class="cvstag">($Id: style-guide.html,v 1.30 2017/11/08 09:42:12 gustafn Exp $)</span></p>
  </div>

</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 12. Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> 
    CVS Guidelines
  </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html>