# Contributing to &arts;

## How You Can Help

The &arts; project can use help from developers to make existing multimedia applications &arts;-aware, write new multimedia applications, and enhance the capabilities of &arts;. However, you don't have to be a developer to contribute. We can also use help from testers to submit bug reports, translators to translate the application text and documentation into other languages, artists to design bitmaps (especially for artsbuilder modules), musicians to create sample &arts; modules, and writers to write or proofread documentation.

## Mailing Lists

Most development discussions on &arts; take place on two mailing lists. This is the place to discuss new feature and implementation ideas or ask for help with problems.

The &kde; Multimedia mailing list is for general &kde; multimedia issues including &arts; as well as the multimedia applications like &noatun; and &aktion;. You can subscribe from the web page at http://www.kde.org/mailinglists.html or send an email with the subject set to `subscribe your-email-address` to kde-multimedia-request@kde.org. The list is also archived at http://lists.kde.org.

The &arts; mailing list is for issues specific to &arts;, including non-&kde; use of &arts;. To subscribe, send an email containing the message body `subscribe your-email-address` to arts-request@space.twc.de. The list is archived at http://space.twc.de/~stefan/arts-archive.

## Coding Standards

For getting a consistent reading through all the sources, it is important to keep the coding style the same, all over the &arts; source. Please, even if you just write a module, try to write/format your source accordingly, as it will make it easier for different people to maintain the source tree, and easier to copy pieces of from one source to another.

Naming of member functions

  &Qt;/&Java; style. That means capitalization on word breaks, and first letter always without capitalization; no underscores.

  This means for instance:

         createStructureDesc()
         updateWidget();
         start();

Class members

  Class members are not capitalized, such as menubar or button.

  When there are accessing functions, the standard should be the &MCOP; way, that is, when having an long member `foo`, which shouldn't be visible directly, you create:

         foo(long new_value);
         long foo();

  functions to get and set the value. In that case, the real value of `foo` should be stored in _foo.

Class names

  All classes should be wordwise capitalized, that means ModuleView, SynthModule. All classes that belong to the libraries should use the &arts; namespace, like Arts::Soundserver.

  The implementations of &MCOP; classes should get called Class_impl, such as SoundServer_impl.

Parameters

  Parameters are always uncapitalized.

Local variables

  Local variables are always uncapitalized, and may have names like `i`, `p`, `x`, &etc; where appropriate.

Tab width (Shift width)

  One tab is as long as 4 spaces.

Spaces in expressions

  You normally don't need to use spaces in expressions. You can however use them between operator and their operands. However, if you put a space before an operator (i.e. +), you also need to put a space after the operator. The only exception to this are list-like expressions (with ,), where you should only put a space after the ",", but not before. It's okay to omit the space here, too.

  The following examples demonstrate good use of spaces:

      {
          int a,b;
          int c, d, e;
          int f = 4;

          a=b=c=d+e+f;
          a = b = c = d + e + f;

          if(a == 4) {
              a = b = c = (d+e)/2;
          }

          while(b<3)
              c--;

          arts_debug("%d\n", c);
      }

  The following examples demonstrate how not to use spaces. For function calls, after if, while, for, switch and so on, no space is being written.

      {
          // BAD: if you write a list, write spaces only after the ","
          int a , b , c , d , e , f;

          // BAD: non-symmetric use of spaces for = operator
          a= 5;

          // BAD: if is considered a function, and isn't followed by a space
          if (a == 5) {
          }

          // BAD: don't write a space after while
          while (a--)
              b++;

          // BAD: functions names are not followed by a space
          arts_debug ("%d\n", c);

          // BAD: neither are member names
          Arts::Object o = Arts::Object::null ();
      }

Naming of source files

  Source files should have no capitalization in the name. They should have the name of the class when they implement a single class. Their extension is `.cc` if they refer to &Qt;/&GUI; independent code, and `.cpp` if they refer to &Qt;/&GUI; dependant code. Implementation files for interfaces should be called `foo_impl`, if Foo was the name of the interface.

  &IDL; files should be called in a descriptive way for the collection of interfaces they contain, also all lower case. Especially it is not good to call an &IDL; file like the class itself, as the .mcopclass trader and type info entries will collide, then.