[Openvas-devel] Change Request #19: discussion open

Stjepan Gros sgros.ml at gmail.com
Thu Nov 20 13:01:06 CET 2008


I'm reposting this. I mistakenly used Reply instead of 'Reply all'.
Sorry for inconvenience.


Just a few comments/suggestions....

On Wed, Nov 19, 2008 at 10:55 AM, Felix Wolfsteller
<felix.wolfsteller at intevation.de> wrote:
> Hi
> I opened CR #19 in the hope that we agree on some formatting and documentation
> rules ( http://www.openvas.org/openvas-cr-19.html ).
>
> As I see it, there are no alternatives to doxygen. If we agree on doxygen we
> further have to agree on a doxygen configuration file (as long as
> documentation is local -> trivial) and on a style for the documentation
> blocks itself, as there are several possibilities (
> http://www.stack.nl/~dimitri/doxygen/docblocks.html ).
> I opt for the javadoc-like style ( e.g. @param ).
>
> Note that I myself will not participate in huge discussions about where to put
> a space, a bracket, a newline etc, as the main aim is that we 1) agree on one
> style and 2) gradually bring a consistent look into the OpenVAS code base and
> 3) achieve professional documentation.
> That means, I will agree to everybody with a strong opinion.

I have few suggestions regarding formatting style. But first, I have
to say that the biggest problem while trying to change code was the
lack of readability because on some places only one space is used for
indent, while at some other places indenting was wrong.

What I wanted to suggest is that proposed code formatting should be
based on some other popular open source project. That way it will be
easier for newcomers to use it, especially if the given style is
accepted in a large number of projects. For that matter I would
propose using Linux Kernel guidelines. There is CodingStyle document
that can be transfferend to OpenVAS. Additional notes could be placed
in a separate files, or in the same file clearly marked as
differences.

The second suggestion is that it should be (relatively) easy to do
automatic reformatting using indent tool. The reason is that it's hard
to expect that newcomers, but even experienced users, will follow
closely formatting rules. Using indent the burden of style
checking/correcting could be automated.

>
> Attached is a first proposal for an example file. It is based on
> slad_install.c and not intended to be compiled.

The file looks good, even though I would personally do some thing
differently, but it's not so important as long as the code is
readable.

Stjepan


More information about the Openvas-devel mailing list