OpenVAS Transfer Protocol (OTP)TopMaintaining ChangeLogSource Code Style Guide

Source Code Style Guide

Because several styles have been mixed into OpenVAS over the last years (most inherited from the old Nessus times), the OpenVAS developers searched an agreement on source and documentation formats.

The result of this Change Request was to follow the formatting recommendations of the GNU Project

(

http://www.gnu.org/prep/standards/standards.html#Formatting
) and to use doxygen with in-code Javadoc style comments

(

http://www.stack.nl/ dimitri/doxygen/docblocks.html
).

This defines how both new and changed OpenVAS source code should ideally be formatted and documented.

The features in a nutshell

Below, an example file with some comments can be seen (not meant to be compiled and not available in the repository).

/* OpenVAS-Client
 * $Id$
 * Description: Proposed formating example (altered slad_install.c)
 *
 * Authors:
 * Felix Wolfsteller <felix.wolfsteller@intevation.de>
 *
 * Copyright:
 * Copyright (C) 2008 by Intevation GmbH
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2,
 * or, at your option, any later version 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 St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * In addition, as a special exception, you have
 * permission to link the code of this program with the OpenSSL
 * library (or with modified versions of OpenSSL that use the same
 * license as OpenSSL), and distribute linked combinations including
 * the two. You must obey the GNU General Public License in all
 * respects for all of the code used other than OpenSSL. If you
 * modify this file, you may extend this exception to your version
 * of the file, but you are not obligated to do so. If you do not
 * wish to do so, delete this exception statement from your version.
 */


#include <unistd.h>
#include <gtk/gtk.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "nessus_i18n.h"
#include "module.h"


/**
 * Defines follow the includes which follow the header, are capitalized and can
 * be documented.\n
 * Documentation is done in the source file, not the header file.
 */
#define SOMEDEFINE "fine"


/**
 * Static functions do not neccessarily begin with the module name.
 * @param str Parameters can be described like this.
 */
static void
statfunc (gchar *str)
{
  /* Indentation by 2 blanks, single lines should not exceed 80 chars */
  GtkWidget* m = gtk_message_dialog_new (GTK_WINDOW(NULL),
                                         (GTK_DIALOG_MODAL
                                          | GTK_DIALOG_DESTROY_WITH_PARENT),
                                         GTK_MESSAGE_ERROR, GTK_BUTTONS_OK,
                                         str);
  /* (If 80 chars per line do not suffice, try to break it up nicely) */
  gtk_dialog_run (GTK_DIALOG (m));
  gtk_object_destroy (GTK_OBJECT (m));
}


/**
 * @brief For an overview, I can describe what happens here in one sentence.
 *
 * Non-static functions begin with the name of the module + underscore.
 * @param win Widget to work on.
 * @param data Data to work with.
 * @return String that has to be freed.
 */
char*
module_func (GtkWidget* win, gpointer data)
{
  char buf[1024];
  pid_t p;
  FILE* f;
  /* Structuring by newlines is fine. */

  f = popen (SLADINSTALLER " --ping", "r");

  /* Conditional and loop intendation same as for functions. */
  if (!f)
    {
      statfunc (_("Could not check SLAD installer."));
      return;
    }
  else /* f != NULL */
    {
      statfunc (_("An else"));
    }
  fgets (buf, sizeof (buf), f);
  pclose (f);

#ifndef CYGWIN
  /* Compiled with flag -mwindows, sladinstaller
   * does not answer on stdout.
   * Therefore, this test is only performed on
   * non-CYGWIN systems and simply dropped for
   * CYGWIN. */
  if (strcmp (buf, "pong\n"))
    {
      statfunc (_("Could not execute SLAD installer."));
      return;
    }
#endif /* CYGWIN */

  // Single-line intermediate comments can also start by double slashes.
  p = fork ();
}


OpenVAS Transfer Protocol (OTP)TopMaintaining ChangeLogSource Code Style Guide