# Development Guidelines

## Coding and Module-design guidelines

#### string handling/encoding

- there is no such thing as plain text
- always use Unicode internally
- appropriately encode()/decode() at IO boundaries
  - DB connection (gmPG2.py consumes/produces unicode)
  - files (use codecs.open(..., encoding=...)
  - user input (wxPython consumes/produces u'' unicode strings)
- what is on offer by psycopg2 isn't perfect, but is the recommended way of quoting when outside-of-query parameter passing isn't available and in this way affords some protection against SQL injection attacks (see here and here too): do not create queries by string concatenation but rather always use %s + query arguments (gmPG2.py offers convenience on that)

#### i18n

- wrap all UI strings in _()
- always use %(tag)s instead of %s only for replacement
  - that way, the order of replacements can be changed in the target language
- for timestamp formatting use gmDateTime.py::pydt_strftime()
- mistakes to avoid are explained at the KDE project

#### backend access

- always use the middleware
- do not put SQL directly in the frontend code - except for match providers
- due to limitations in PostgreSQL's inheritance implementation, never ever write to clin_root_item or risk data corruption
  - we have put in rules disallowing write access to this parent table, to prevent this and if we should have an unprotected parent table elsewhere in the schema, let us know

#### more

- do NOT mix tabs and spaces when indenting (tabs preferred, pure space acceptable)

- try providing docstrings (see Python tutorial reference), preferably in EpyDoc style
- comment your code
- use NamingConventions

- each GUI panel should be a black box, communicating with other panels via messages

- using exceptions: suggested to follow
  - guidelines
  - http://www.nedbatchelder.com/text/exceptions-vs-status.html and links from there
  - in Python there is no checked vs unchecked exceptions plus
  - not using the string interface, but only the class interface, on exceptions
  - related email thread here

- wxwindows guidelines at http://wxguide.sourceforge.net/guidelines/content.html

## Key area coordinators

area | coordinators
--- | ---
database schema | KarstenHilbert
schema bootstrapping | KarstenHilbert
i18n issues | KarstenHilbert
middleware/business objects | KarstenHilbert, CarlosMoro
GUI conceptual design | Richard Terry
packaging (Debian) | Andreas Tille
packaging (Gentoo) | DavidGrant
Wiki | Jim Busser
website | Tony Lembke
release management | SebastianHilbert

- demographics & contacts: contact Ian, Richard
- see RoadMap for a listing of required / desired / planned functions
- a historical post on this is at: http://mail.gnu.org/archive/html/gnumed-devel/2003-11/msg00119.html
- DevelopmentProcess gives an overview of just how people's ideas and needs should come together into the project

## rarely needed guidelines

## VCS Guidelines

- Code, test, retest, make sure you did not introduce new bugs, if unsure contact the author of that code or admininistator.
- For anything significant, if you do not receive sufficient feedback within a reasonable timeframe inquire again. Do not assume saying nothing means approval.
- Please, preferably put a README explaining how to run your code into the test directory as soon as you think your code can be tried out by others e.g. if it doesn't run within the otherwise unmodified gnumed framework or is otherwise self-explanatory. Please communicate with us. Your code may be excellent, and it would be a shame if we wouldn't use it because we don't know about it or how to use it.
- take a close look at what code is already in VCS, use existing code whenever possible, enhance existing code whenever necessary
- comment your code (meaning comment everything, even if it might seem stupid to you! ); uncommented code (new files etc. ) will not make it into the main trunk. Some info on commenting limitations of Epydoc here
- submit early and often PROVIDED the code runs, and announce changes to the list

- If you code like crazy in test-area and add new functions to files you are not responsible for (you did not append it initially or have not take over the duty of maintaining the file) do not commit substantial changes without contacting the guy that is responsible for the file.
- original gnumed-devel thread

## Artwork Handling

- a topic has been initiated at Artwork Handling

## Packaging information

- a topic has been initiated at BinaryPackages

## Performance design

- a topic has been initiated at PerformanceDesign

-- JamesBusser - 24 Sep 2004