Naming Conventions

file names

• for python code files use "gm*.py", such as gmAllergy.py
• use CamelCase, eg. gmAllergyManager.py
• do not duplicate file names
• put a docstring at the top of each file specifying the intent of the file
  • http://mail.gnu.org/archive/html/gnumed-devel/2004-05/msg00155.html

code

• start class names with "c", then use CamelCase, such as cAllergy
• start singleton class names with "gm", the use CamelCase, such as gmCurrentPatient
• use underscores for methods, variable, etc, such as method_foo() or allergy_status
• use speaking method and variable names (allergies = ... instead of a = ...)
• follow also these recommendations for meaningful names
• code in english for coding, but internationalize for display (using gettext)

database

• in the database table schema
  • pk for primary keys
  • fk_* for foreign keys in tables
  • pk_* for both primary and foreign keys in views
    • The rationale is that in tables, fk_, eg fk_marital_status or fk_identity refer to "real" foreign keys. However a view is just an aggregation of fields, eg of several primary keys and their associated data. Since the foreign keys are coming from several tables it is impossible to say in a view what is a foreign key and what isn't in most cases. Hence all of them are pk_*.
  • ufk_* for unmatched foreign keys

client

• On-screen labels and menu item spellings "Upper lower" e.g. lock client, provider inbox --> Lock client, Provider inbox e.g. GNUmed > Options > User Interface ----> User interface?

older information

regularize naming for clarity and efficiency e.g.

> - 3 tables: lnk_org2comm_channel, lnk_org2ext_id, lnk_org2address
> - the equivalent 3 tables regularised in naming:
> lnk_identity2comm_channel, lnk_identity2ext_id, lnk_identity2address, so
> we can use the same client business code for both with these 3 aspects, as
> their behaviour is identical. I appreciate for other aspects (i.e. names)
> we need separate code as they behave quite differently. --- Richard Terry http://mail.gnu.org/archive/html/gnumed-devel/2004-03/msg00078.html and

Proposed forms system - I was thinking of a set naming scheme viz. $GNUMED_BASE_DIR/templates/$LOCALE/$DISCIPLINE.$VERSION.tex so /au/script.1..tex is the AU PBS script, /de Physiotherapie.1.tex is the form for a german physio referral. If a discipline does not have a form, a 'default form" is used (in AU, we only need the default form of course)---Ian http://mail.gnu.org/archive/html/gnumed-devel/2003-11/msg00230.html

do not change names, only deprecate them e.g.

Oh, the woes and powers of improper naming ! We got into this quagmire when someone assumed that since there is a getActiveName() there ought to be a setActiveName(), too. This is all nice and well with certain branches of programming theory but it doesn't make sense in the business object API. The name is simply ambiguous. Is it supposed to be activate_name() or add_name_and_activate() ? (My UPDATE on a names row violated our business agreement anyways as we don't change name records, only deprecate them.) Hence we shall decide to deprecate setActiveName in favour of addName(). Upon which clarification we find out that we can add a flag argument "activate" without introducing any more ambiguity. addName() internally SELECTs add_name() which is a stored procedure trying to take care of some issues such as the name to be added already existing for this person. It, too, handles the activate flag.---Karsten http://mail.gnu.org/archive/html/gnumed-devel/2003-11/msg00204.html

Miscellaneous

At the moment, usability bugs might be of a concern, but the logic is pretty simple ( just store names and cross references, and use the cursor description, and move back and forth between names for widgets vs names for tables, fields and references. The only naming dependency is that table have a non-composite primary key called id, references are named id_xxxxx where xxx is the referenced table, and the single named target table is at the top of the reference tree. one-to-many relationships aren't handled yet ---Syan http://mail.gnu.org/archive/html/gnumed-devel/2003-10/msg00024.html

When formal docs are lacking, the code can make all the difference. I have been commenting undocumented code before. But that was understandable code and its intent was intuitive by good naming of variables, methods, and classes. Applying the lingo of a certain programming language goes a great deal towards self-documenting code. I too, of course, have been subject to justified requests for documentation by, say, Hilmar.---Karsten http://mail.gnu.org/archive/html/gnumed-devel/2003-05/msg00168.html

A compilation note about how Epydoc treats python code and extracts its comments --- Jim http://lists.gnu.org/archive/html/gnumed-devel/2004-06/msg00211.html

-- JamesBusser - 15 Jul 2004