Coding Style¶

Match braces¶

Align braces in same column.

  struct mystruct 
  {
    int myvar;
  };

NOT

  struct mystruct {
    int myvar;
  };

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

Tabs¶

• Don't insert tabs into the source file.
• Set your editor translate a tab into two spaces.

Indent Offset¶

Use two spaces as indent offset.

    for (i=0; i<bufsize; i++)
    {
      buf[i] = tolower(buf[i]);
      if(buf[i] < 0) 
      {
        buf[i] = 127;
      }
    }

NOT

    for (i=0; i<bufsize; i++)
    {
            buf[i] = tolower(buf[i]);
            if(buf[i] < 0) 
            {
                    buf[i] = 127;
            }
    }

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)

Doxygen¶

The source documentation is embedded in the code and parsed by doxygen. Use Doxygen commands. A typical doc header looks like:

  /*!
   * \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)

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

  /***************************************************************
  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.
  ***************************************************************/

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

Comments¶

Comments are good. Use them.
When commenting a variable, indent the comment starting on the same line

struct regex_file_struct
{
  int      ftype1;          /* 1=filename, 2=license 
                             * 3=bucket, 4=tag       */
  char    *regex1;          /* regex1 string         */
  regex_t  compRegex1;
};

NOT

struct regex_file_struct
{
  /* 1=filename, 2=license */
  int      ftype1;
  /* regex1 string */
  char    *regex1;
  regex_t  compRegex1;
};

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.

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;
}

Internationalization¶

Internationalization