If you consider naming variables, you are in a country-specific repository, where the local language rule apply. The domain language is thus one of the native ones of the modeled country. We consider each tax, collecting organism and country regulation as a domain-specific term. In the same fashion, well-known abbreviations of these domain-specific terms are accepted.
OpenFisca variables names should, as much as possible, be understandable by an external contributor who is curious about the country tax and benefits system, without necessarily being an expert.
One should be able to get a rough idea of the meaning of a variable by reading its name, or by quickly researching it on the web.
A particular effort should be made on variables that are likely to be reused.
Examples:
Good naming
als_etudiant: I don’t know whatalsstands for. I look it up on a search engine, and I see ALS are a form of Aides Logement. I thus know this variable should be the amount of ALS for a student. This is enough to tell me if it is interesting in my context.
Bad naming
apje_temp: I could find the meaning of APJE online, but the temp suffix remains a mystery.
rto_net. I can guess it’s an amout after some kind of deduction, but looking RTO on a search engine doesn’t give me anything.
Acronyms are ok as long as they are broadly accepted and their meaning is quickly findable online.
OK: RSA, RFR
KO: PAC
Abbreviations should be avoided unless they are undoubtedly transparent.
OK: nb_parents
KO: nb_par, isol
To show a variable belongs to a specific scope, it is better to use a prefix rather than a suffix.
OK: rsa_nb_enfants
KO: nb_enfants_rsa
Not specifying the scope of a specific variable should be avoided, as it is confusing for other users.
OK: ir_nb_pac
KO: nb_pac
It happens that several variables have the same meaning, but for different entitities (individus, familles, etc.). Standard suffixes should be used to distinguish them.
OK: ass_base_ressources_individu, statut_occupation_logement_famille
Many variables on the current codebase of OpenFisca France do not respect the guidelines presented here. An exhautsive and global renaming is not considered as of today.
However, new variables should be compliant with these guidelines, and legacy ones should progressively and opportunistically be renamed.