Personal tools
You are here: Home documentation developer Code Guidelines
Views
Code Guidelines copied

As for repository guidelines developed over time on this list, here are some (which should be properly documented):

naming:

  • general -- object names are often stored on the filesystem; keep in mind that there are popular filesystems that do not allow special characters or names; there are filesystems that have no notion case sensitivity, but others do.

    • - all lib names and all sections in the repository are lowercase only (name them how ever you want in the web-page, etc. but the lib and the directory in /externals/ need to be all lowercase (there are only three exceptions AFAIK, Gem, miXed, and OSCx, and these are legacy) - class names should be all lowercase (except for cyclone, which needs to use upper case for Max/MSP compatibility) - class names with multiple words in the name should use underscores to separate words (i.e [iem_anything_kernel], [curve_log], [define_loudspeakers], [my_canvas], etc.) - class names should not contain spaces

    conversions -- several naming conventions for objects that do type conversion have been established. It is still **subject to discussion**, which one should be used. Choose one of the available forms.
    • - Native Pd objects use the convention 'oldtype + "to" + newtype', i.e. [ftom].

      • (Simple, but not very readable: is it "a-to-m" or "a-tom" or "at-om" or even "atom"?)

      - Another popular form is to use 'oldtype + "2" + newtype', i.e. [list2symbol].
      • (good separation between oldtype and newtype, as long as no numbers are involved in both names: e.g. [m22i2] could mean converting between square meters and square inches, but probably a lot of other things too)

      - 'old-type + "->" + new-type', i.e. [cart->pol], [mapping->radians], [gem->pdp].
      • (good separation between oldtype and newtype, but needs to use hex character replacement due to filesystem limitations)

      - There should be no spaces or underscores between the types!
    file layout -- people have argued a lot about whether it is better to organize objects in big libraries (one (1) file which contains several objects) or in single externals (each object-class has its own file).
    • With pd-patches the answer is simple, since one '.pd' file can only define one single object. However, compiled objects (e.g. written in C) can be organized in both ways, and both have their good and bad sides. In order to make the differences between the two approaches not too big, - the files should be named the same as the object [hid] = hid.c, [moog~] = moog~.c - the classes should be able to be compiled in the single-class/single-file format (its fine to also build the multiple-class/single-file format in addition)

    namespaces -- objects with similar names but different functionality in different libs
    • - the geiger namespace makes class name prefixes like "sp_" unnecessary. - A better solution would be a more descriptive name if you want to differentiate your class from another class with the same name.

Code Formatting

  • indentation -- the Pd core source code is formatted using a tab width of 8 and an indent of 4. There is a wide degree of varying styles in other code, for better or worse.



Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser