FOSSology

h1. Coding Style

h2. Match braces

Align braces in same column.

<pre>

  struct mystruct 

  {

    int myvar;

  };

</pre>

**NOT**

<pre>

  struct mystruct {

    int myvar;

  };

</pre>

This is a general rule for braces.  It applies to switch statements, blocks under if statements, function blocks, ...

h2. Tabs

* Don't insert tabs into the source file.  

* Set your editor translate a tab into two spaces.

h2. Indent Offset

Use two spaces as indent offset.

<pre>

    for (i=0; i<bufsize; i++)

    {

      buf[i] = tolower(buf[i]);

      if(buf[i] < 0) 

      {

        buf[i] = 127;

      }

    }

</pre>

**NOT**

<pre>

    for (i=0; i<bufsize; i++)

    {

            buf[i] = tolower(buf[i]);

            if(buf[i] < 0) 

            {

                    buf[i] = 127;

            }

    }

</pre>

h2. Local Function Names

Don't use an underscore to denote local functions.

  void  entry_print(void* to_print, FILE* ostr)

**NOT**

  void  _entry_print(void* to_print, FILE* ostr)

h2. Doxygen

The source documentation is embedded in the code and parsed by doxygen.  Use "Doxygen commands.":http://www.stack.nl/~dimitri/doxygen/commands.html A typical doc header looks like:

<pre>

  /*!

   * \brief analyze a file for the copyright information

   *

   * This will open and analyze the file provided. It is important to note that

   * this function will clear any information that was previously stored in copy.

   * All information that is needed should be extracted from copy after a call to

   * analyze before calling analyze again.

   *

   * \param copy the copyright instance that will be analyzed

   * \param file_name the name of the file to be openned and analyzed

   *

   * \return 0 on OK, -1 on failure.

   * 

   * \todo blah blah

   */

  void copyright_analyze(copyright copy, FILE* istr)

</pre>

There are many other useful doxygen commands, including:

  \code ... \endcode

  \verbatim ... \endverbatim

  \li

  \n

===== Copyright =====

Each source file should have a copyright notice.  For HP developers, this looks like

<pre>

  /***************************************************************

  Copyright (C) 2008-2010 Hewlett-Packard Development Company, L.P.

  This program is free software; you can redistribute it and/or

  modify it under the terms of the GNU General Public License

  version 2 as published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful,

  but WITHOUT ANY WARRANTY; without even the implied warranty of

  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along

  with this program; if not, write to the Free Software Foundation, Inc.,

  51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

  ***************************************************************/

</pre>

And don't forget to update the year when a file is modified.

h2. Comments

Comments are good.  Use them.

When commenting a variable, indent the comment starting on the same line

<pre>

struct regex_file_struct

{

  int      ftype1;          /* 1=filename, 2=license 

                             * 3=bucket, 4=tag       */

  char    *regex1;          /* regex1 string         */

  regex_t  compRegex1;

};

</pre>

**NOT**

<pre>

struct regex_file_struct

{

  /* 1=filename, 2=license */

  int      ftype1;

  /* regex1 string */

  char    *regex1;

  regex_t  compRegex1;

};

</pre>

h2. SQL 

The current code base has sql scattered in each file that executes a sql statement.  The problem with this is that we sometimes have multiple statements to accomplish the same task.  Sometimes both versions work correctly and sometimes they don't.  I propose that we start a /ui/common/common-sql.php to define common functions to return results.  For example, one common function is to get all the non-artifact uploadtree records in an upload or subtree.  

<pre>

function GetUploadtreeResult($upload_fk, $lft="", $rgt="")

{

  global $PG_CONN;

  if (empty($upload_fk)) return NULL;

  /* Missing $lft or $rgt means to return results for the

   * whole upload instead of a subtree 

   */

  if (empty($lft) || (empty($rgt)))

    $LftRgtCondition = "";

  else

    $LftRgtCondition = "and lft>'$lft'  and rgt<'$rgt'";

  $sql = "select uploadtree_pk, ufile_name, lft, rgt from uploadtree 

            where upload_fk='$upload_fk' 

              $LftRgtCondition

              and ((ufile_mode & (1<<28)) = 0)";

    $outerresult = pg_query($PG_CONN, $sql);

    DBCheckResult($outerresult, $sql, __FILE__, __LINE__);

  return $outerresult;

}

</pre>

h2. Internationalization

[[i18n#step_2_-_separate_message_text_from_code | Internationalization]]