Discussion: Naming Convention for (Public) API

[SSoelvsten]

While looking at the public API as a whole, I have been wondering once again "Is there really not a pretty interface?". I personally like snake_case and have a slight aversion to camelCase. Furthermore, both the std and tpie library use this style, which makes Adiar's codebase consistent.

What I personally would hope for is something that would look like this.

if (adiar::bdd::is_true(f)) {
  adiar::bdd h = adiar::bdd::and(f,g);
}

Here the function and(f,g) is a static function of the bdd class. Yet, since and, or, and xor are keywords in C++ (due to historical reasons), this is a mere utopian dream of mine.

I hope this issue can foster a discussion for what would be the preferred naming scheme. I would then switch to the result of this conversation when releasing Adiar v2.0 (or more likely first with v3.0). Please add your thoughts/vote in a comment below.

Option 1: {prefix}_{nocase} (current)

if (adiar::bdd_istrue(f)) {
  adiar::bdd h = adiar::bdd_and(f,g);
}

Arguments: This style matches the C and C++ interface of BuDDy and the C interface of Sylvan. Furthermore, it does not clash heavily with the use of snake_case in the rest of the codebase.

Option 2: {prefix}_{camelCase}

if (adiar::bdd_isTrue(f)) {
  adiar::bdd h = adiar::bdd_and(f,g);
}

Arguments: This style is close to the current API while being slightly easier on the eyes. Yet, question is whether the rest of the codebase then needs to switch to a camelCase style to be consistent? If so, what should change and what should be kept - and why?

Option 3: {Prefix}_{CamelCase}

if (Adiar::BDD::IsTrue(f)) {
  Adiar::BDD h = Adiar::BDD::And(f,g);
}

Arguments: This style circumvents the keywords by capitalizing the first symbol. Yet, by switching to CamelCase on the function, the style propagates to the class name bdd (which either should be Bdd or BDD). Yet having the namespace still uncapitalized looks really weird, so the namespace also changes.

Furthermore, this truly calls for the entire codebase to change its naming scheme.

Option 4: make_/is_ prefix

if (adiar::is_true(f)) {
  adiar::bdd h = adiar::make_and(f,g);
}

Arguments: This style is close to the std, it nicely highlights what functions construct new BDDs and which ones do not. Yet, now we have name clashes between the bdd and the zdd namespaces.

Option 5: Synonyms for and, or, and xor

if (adiar::bdd::is_true(f)) {
  adiar::bdd h = adiar::bdd::conj(f,g);
}

Maybe we can get around this entire issue by finding synonyms for the unfortunate keywords (without running into new ones)

• and: conj, ...
• or: disj, ...
• xor: eor, exor, ...

Arguments: This achieves the desired style at the cost of having odd choice for names of the three most common operators.

[SSoelvsten]

On email, Andrew Miner has sent me the following preference due to consistency:

• (1) {prefix}_{nocase}
• (3) {Prefix}::{CamelCase}

[SSoelvsten]

On email, Jaco van de Pol believes all three naming schemes would work. But, he has the following preference list:

• (2) {prefix}_{camelCase}
• (1) {prefix}_{nocase}
• (3) {Prefix}::{CamelCase}

[SSoelvsten]

On email, Anna Blume Jakobsen sent me the following preference list:

• (2) {prefix}_{camelCase}
• (1) {prefix}_{nocase}
• (3) {Prefix}::{CamelCase}

[SSoelvsten]

Talking with Erik Funder Carstensen (a non-BDD user and hence an unbiased third-party), he advocates for being consistent with BuDDy and Sylvan (i.e. not only should Adiar have a consistent API, but it should maintain an inter-library consistency)

• (1) {prefix}_{nocase}

[SSoelvsten]

Talking with Fabian Pieroth (a non-BDD user and hence an unbiased third-party), prefers:

• (2) {prefix}_{camelCase}
• (1) {prefix}_{nocase}

[SSoelvsten]

On email Henrik Bærbak Christensen also emphasizes to be consistent with what is expected in a language (and other relevant contexts). That is, he argues for (1) or (3).