English | Deutsch
Home »

OpenVAS Change Request #19: Agree on a style guideline and on a format for the documentation

Status: Voted + 5, in the OpenVAS Compendium Rev. 2100.

Purpose

To ease further developement of all OpenVAS modules.

To improve readability of source code.

To have an appropriate section in the OpenVAS Compendium for the people interested in making OpenVAS even better.

References

Rationale

In the OpenVAS code base one can find that too many different conventions about code formatting and code documentation were used. This makes it difficult for developers that are new to the OpenVAS project to look at the code and get a fast overview. Furthermore, there is a certain lack of documentation, and no extensive documentation of the API exists.

There are guidelines given in the OpenVAS Compendium, but the section is short and no "standard" is stated.

If the currently active developers agree on one style (e.g. on one favorite file) this can be set as a standard for future developements and documented in the OpenVAS Compendium.

Effects

This agreement and enhanced section in the OpenVAS Compendium allows current source developements to look the same, thus enhancing readability and reducing the currently high demand of reading and understanding the code at the same time.

Furthermore it allows to use tools to automatically extract an API documentation, which in turn can help the developers to understand OpenVAS. If this API documentation reaches a certain quality, it can be made available online and become included into -dev or -doc packages.

Future developements would thus look the same and be documented. Old code, however, would stay untouched. Style changes would become applied gradually, e.g. when code in the same file is touched, to not make svn blames too difficult.

Design and Implementation

After discussions on the developers mailinglist, agreement fell on the GNU Coding Style Guide and the use of doxygen with Javadoc- style comments.

A standard Doxyfile was added to the repository.

The OpenVAS Compendium was updated.

History