Naming Conventions

file names

  • for python code files use gm*.py and CamelCase, eg. gmDocumentWidgets.py
  • for bootstrapper SQL scripts use vXX-schema-table|view_name-dynamic|static.sql, say v16-dem-v_basic_person-dynamic-sql where vXX refers to the database this script is to go into
  • do not duplicate file names
  • put a docstring at the top of each file specifying the intent of the file

code

  • start class names with c, then use CamelCase, such as cAllergyState
  • start singleton class names with "gm", the use CamelCase, such as gmCurrentPatient
  • use lowercase + 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 _() on strings)

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.

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 does SELECT 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
Topic revision: 14 Jul 2011, KarstenHilbert
 
Download.png
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback
Powered by Olark