Guidance in naming awkward domain-specific objects?

Question

I'm modeling a chemical system, and I'm having problems with naming my elements / items within an enum.

I'm not sure if I should use:

• the atomic formula
• the chemical name
• an abbreviated chemical name.

For example, sulfuric acid is H2SO4 and hydrochloric acid is HCl.

With those two, I would probably just use the atomic formula as they are reasonably common.

However, I have others like sodium hexafluorosilicate which is Na2SiF6.

In that example, the atomic formula isn't as obvious (to me) but the chemical name is hideously long: myEnum.SodiumHexaFluoroSilicate. I'm not sure how I would be able to safely come up with an abbreviated chemical name that would have a consistent naming pattern.

There are a few problems that I'm trying to address through naming the enum elements.
The first is readability, with the longer names presenting an issue.
The second is ease of picking up the code for new maintainers, and here the shorter names present an issue.
The next issue is the that business owners usually refer to the full chemical name, but not always. The "mouthful" chemicals are referred to by their formula.
The final concern is making sure it's consistent. I don't wan't a mixed naming convention as it will be impossible to remember which to use.

From a maintenance point of view, which of the naming options above would you prefer to see and why?

---

Note: Everything here below the line is supplementary | clarifying material. Please don't get bogged down in it. The main question regards naming the awkward objects.

Atomic Option

public myEnum.ChemTypes
{  
   H2SO4,
   HCl,
   Na2SiF6
}

Chemical Name Option

public myEnum.ChemTypes
{
   SulfuricAcid,
   HydrochloricAcid,
   SodiumHexafluorosilicate  
}

---

Here are some additional details from the comments on this question:

• Audience for the code will be just programmers, not chemists.
• I'm using C#, but I think this question is more interesting when ignoring the implementation language.
• I'm starting with 10 - 20 compounds and would have at most 100 compounds, so I don't need to worry about every possible compound. Fortunately, it's a fixed domain.

• The enum is used as a key for lookups to facilitate common / generic chemical calculations - which means that the equation is the same for all compounds but you insert a property of the compound to complete the equation.

  • For example, Molar mass (in g/mol) is used when calculating the number of moles from a mass (in grams) of the compound. FWIW, Molar Mass == Molar Weight.
  • Another example of a common calculation is the Ideal Gas Law and its use of the Specific Gas Constant

A sample function might look like:

public double GetMolesFromMass(double mass_grams, myEnum.ChemTypes chem)
{
  double molarWeight = MolarWeightLookupFunctionByChem(chem); //returns grams / mole
  double moles = mass / molarWeight;  //converts to moles

  return moles;
}

//Sample Call:
myMoles = GetMolesFromMass(1000, myEnum.ChemTypes.Na2SiF6);
//*or*
myMoles = GetMolesFromMass(1000, myEnum.ChemTypes.SodiumHexafluorosilicate);

public double GetSpecificGravity(myEnum.ChemTypes chem, double conc)
{
  //retrieves specific gravity of chemical compound based upon concentration
  double sg = SpecificGravityLookupTableByChem(chem, conc);  
}

So the enum of the compound name is used as a key and to provide consistency in referencing the compound with the related functions.

Answer 1

When I started rewriting my current project from spaghetti into reasonable code, I was faced with the same problem. My problem domain is medical, and rather than use names like "ETCO2" and "SPO2" for my enums I used the full English names.

On the one hand, it was very useful to have English names when I was new to the problem domain. On the other hand, now that I've been working with these terms for a year I find that the full English names are far too verbose and I'm familiar enough with the terms that I'd much prefer to use the abbreviations.

My advice would be to use the atomic formula and include a comment by each enum value that gives its full name, on the assumption that anyone who looks at your code will either be a) a chemist, or b) working on the code long enough that they naturally become familiar with the formulae.

Answer 2

Who is the audience for the code? Will chemists be using the Enums, or just programmers without specific domain training in chemistry?

If chemists will be using the code, ask them. Very likely they will prefer the abbreviated symbols, as they can readily recognize them. If general-knowledge programmers will be using these identifiers on behalf of the chemists, I think it's better to go with the English-like versions.

Answer 3

No reason not to combine "all the above."

The problem with the full names is it will be tedious to type, the problem with the symbol names is lack of meaning.

So, create constants of the values with the full name. Then create defines associated with the constant. You can easily then create newer,shorter defines as you become more familiar with the meaning of the abbreviation.

const int SodiumHexaFluoroSilicate = 16893859;   
const float Gold = 196.966569;

#define SoduimSilicate SodiumHexaFluoroSilicate 
#define F6Na2Si SodiumHexaFluoroSilicate 
#define au Gold 

Answer 4

When you design any application, you should separate the data from the program logic. Are the chemical compounds really part of the program logic and not rather the data the program logic is operating on?

When they are data, it would be much better to not treat them as enums but rather read their names and properties from a configuration file and store them in a data structure. That would also make maintainance a lot easier. When one needs to add new compounds, or finds an error in the properties of one, they can just edit the configuration file.

Answer 5

This seems like it could be better implemented as a class that can expand and translate based on the developers' needs. Below is some sample C# I came up with to allow for a few well-known defined chemicals (as properties) and then queryable stores (via Add and Get methods). You can also extend pretty easily to have your molar mass and other chemical properties available.

public interface IChemical
{
    string AtomicFormula
    {
        get;
    }

    string ChemicalName
    {
        get;
    }

    string AbbreviatedChemicalName
    {
        get;
    }
}

public sealed class Chemical : IChemical
{
    private static readonly IChemical h2so4 = new Chemical("H2SO4", "sulfuric acid", "sulf. acid");

    private static readonly IChemical hcl = new Chemical("HCl", "hydrochloric acid", "hydro. acid");

    private static readonly IDictionary<string, IChemical> chemicalsByAtomicFormula = new Dictionary<string, IChemical>();

    private static readonly IDictionary<string, IChemical> chemicalsByChemicalName = new Dictionary<string, IChemical>();

    private static readonly IDictionary<string, IChemical> chemicalsByAbbreviatedChemicalName = new Dictionary<string, IChemical>();

    private readonly string atomicFormula;

    private readonly string chemicalName;

    private readonly string abbreviatedChemicalName;

    static Chemical()
    {
        chemicalsByAtomicFormula.Add(h2so4.AtomicFormula, h2so4);
        chemicalsByChemicalName.Add(h2so4.ChemicalName, h2so4);
        chemicalsByAbbreviatedChemicalName.Add(h2so4.AbbreviatedChemicalName, h2so4);
        chemicalsByAtomicFormula.Add(hcl.AtomicFormula, hcl);
        chemicalsByChemicalName.Add(hcl.ChemicalName, hcl);
        chemicalsByAbbreviatedChemicalName.Add(hcl.AbbreviatedChemicalName, hcl);
    }

    public Chemical(string atomicFormula, string chemicalName, string abbreviatedChemicalName)
    {
        if (string.IsNullOrWhiteSpace(atomicFormula))
        {
            throw new ArgumentException("Atomic formula may not be null or whitespace.", "atomicFormula");
        }

        if (string.IsNullOrWhiteSpace(chemicalName))
        {
            throw new ArgumentException("Chemical name may not be null or whitespace.", "chemicalName");
        }

        if (string.IsNullOrWhiteSpace(abbreviatedChemicalName))
        {
            throw new ArgumentException("Abbreviated chemical name may not be null or whitespace.", "abbreviatedChemicalName");
        }

        this.atomicFormula = atomicFormula;
        this.chemicalName = chemicalName;
        this.abbreviatedChemicalName = abbreviatedChemicalName;
    }

    public static IChemical H2SO4
    {
        get
        {
            return h2so4;
        }
    }

    public static IChemical HCl
    {
        get
        {
            return hcl;
        }
    }

    public string AtomicFormula
    {
        get
        {
            return this.atomicFormula;
        }
    }

    public string ChemicalName
    {
        get
        {
            return this.chemicalName;
        }
    }

    public string AbbreviatedChemicalName
    {
        get
        {
            return this.abbreviatedChemicalName;
        }
    }

    public static void AddChemical(IChemical chemical)
    {
        if (chemical == null)
        {
            throw new ArgumentNullException("chemical", "chemical may not be null");
        }

        if (chemicalsByAtomicFormula.ContainsKey(chemical.AtomicFormula))
        {
            return;
        }

        chemicalsByAtomicFormula.Add(chemical.AtomicFormula, chemical);

        if (chemicalsByChemicalName.ContainsKey(chemical.ChemicalName))
        {
            return;
        }

        chemicalsByChemicalName.Add(chemical.ChemicalName, chemical);

        if (chemicalsByAbbreviatedChemicalName.ContainsKey(chemical.AbbreviatedChemicalName))
        {
            return;
        }

        chemicalsByAbbreviatedChemicalName.Add(chemical.AbbreviatedChemicalName, chemical);
    }

    public static IChemical GetChemicalByAtomicFormula(string atomicFormula)
    {
        if (string.IsNullOrWhiteSpace(atomicFormula))
        {
            throw new ArgumentException("Atomic formula may not be null or whitespace.", "atomicFormula");
        }

        IChemical chemical;

        return chemicalsByAtomicFormula.TryGetValue(atomicFormula, out chemical) ? chemical : null;
    }

    public static IChemical GetChemicalByChemicalName(string chemicalName)
    {
        if (string.IsNullOrWhiteSpace(chemicalName))
        {
            throw new ArgumentException("Chemical name may not be null or whitespace.", "chemicalName");
        }

        IChemical chemical;

        return chemicalsByChemicalName.TryGetValue(chemicalName, out chemical) ? chemical : null;
    }

    public static IChemical GetChemicalByAbbreviatedChemicalName(string abbreviatedChemicalName)
    {
        if (string.IsNullOrWhiteSpace(abbreviatedChemicalName))
        {
            throw new ArgumentException("Abbreviated chemical name may not be null or whitespace.", "abbreviatedChemicalName");
        }

        IChemical chemical;

        return chemicalsByAbbreviatedChemicalName.TryGetValue(abbreviatedChemicalName, out chemical) ? chemical : null;
    }
}

you can add new chemicals like such:

        Chemical.AddChemical(new Chemical("Na2SiF6", "sodium hexafluorosilicate", "sod. hex.flu.sil."));

and get the other bits as such:

        Console.WriteLine(Chemical.GetChemicalByChemicalName("sulfuric acid").AtomicFormula);