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 (DB-API should do it)
  • files
  • user input
• 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).

i18n

• wrap all UI strings in _()
• always use %(tag)s instead of %s only for replacement
  • that way, the order of replacements can changed in the target language
• always use the locale aware formatting of mx.DateTime for timestamp formatting
• 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)

• use docstring (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

• see relevant online documentation at http://gnumed.net/whitepapers/messenging.html and http://gnumed.net/whitepapers/signals.html
• wxwindows guidelines at http://wxguide.sourceforge.net/guidelines/content.html

Key area coordinators

• 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

CVS Guidelines

• Note: CVS won't let you delete obsolete directories, only obsolete the contents and put it in "attic". Therefore please do not create any new directories (except if appropriate in test-area) until after agreement by the group. CVS does let you hide empty directories by use of the -P switch. People may want to put that in their ~/.cvsrc file to simplify their lives. Filenotes: 1. last post re this 2. code location within CVS
• Concerning commits, the most important rule is that you have to think before committing.
• 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.

1. take a close look at what code is already in CVS, use existing code whenever possible, enhance existing code whenever necessary
2. start your work in gnumed/test-area/ which is also where any large, sweeping, experimental changes should go (Note: it is further planned to to branch off stable and devel once a version 0.1 release is tagged. If in the meantime you want to test some GUI part that does not change the basic workings, you can simply write a notebook plugin for the initial notebook design.)
3. 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
4. if you have a good idea and it works for you at home, please
   • dump the database
   • pack the dump together with all dependent scripts into a tar file so that we can test it in isolation without having to modify the code too much
5. If making changes that are to go into the main trunk, test them before checking in, update the public database, and announce them on the mailing list
6. the ONLY commits to CVS must be small AND working -OR- peer reviewed -OR- for an area/file that YOU are maintaining (see bullet at bottom)
7. patches not meeting the above will not make it into the CVS main trunk
8. when doing a cvs commit, know which files you actually changed and ALWAYS explicitly name them for the commit.
   • never commit files you did not change
   • be wary of using GUI frontends that tend to force the user to commit touched (but unchanged) files. Good practice is to use the update_tree.sh script in the tree and check the produced diff, to know which files were changed how. It is then possible to selectively check in only those changed files, i.e. those one really wants, by explicitly naming them in the commit command.
   • add commit comments to each file you commit !!!
   • If you fear messing up something:
     1. you can always post/mail for review first
     2. you can always check in under test_area/ first
9. submit early and often PROVIDED the code runs, and announce changes to the list
10. be aware that huge patches will most likely be ignored by peer reviewers unless they agree with it 1 wanna code your own client ? That's perfectly fine. Please stick to test-area for that!

• 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