Camel and snake here are just metaphoras. The terms snake case and camel case in programming mostly refers to object naming style. Some might write API query parameter createdAt and some created_at or sortBy and sort_by. The latter case in the both examples is snake_case. By the way, if the logic of Camel Case would be followed rigidly (which it is not) the param names should be CreatedAt and SortBy. Why the first letter is not capital letter? The reason is that even inside the camel case you have two variations: Upper CamelCase (PascalCase) and (lower) camelCase.

What are the case options?

Mostly the discussion is around snake case (snake_case) and camel case (CamelCase). Following the discussion might look at first mostly religious battles, but there’s something more behind it too. People don’t pick one or the other “just because”. Oh well some might just adopt one because that’s the one I’ve seen most. And that is valid and logical reason to pick one! If case type in your preferred programming language is snake case, it’s only natural that you adopt it and stick with it even outside the daily scope. Though not all might agree with you for example if you use snake case in REST API query parameter names.

But wait, there’s more! There is also kebab-case also known by aliases spinal case, param case, Lisp case, and dash case. This is normally used in URLs. The dash does not disappear/lose visibility (for humans) if presented as a html link / url. Underscore gets hidden in such cases.

Furthermore I found Studly caps as well, but sounds just ridiculous if you read what it is: “Sometimes only vowels are upper case, at other times upper and lower case are alternated, but often it is simply random.” Probably good for some weird random unique id generation but not for variable or API query parameter names.

Rule 1: If you provide code examples in API docs (recommended), then follow the convention of the language. That does not however imply that your API should support for example snake case and camel case in query parameters. Pick one style and be consistent. For the rest of the code, follow the language convention. In the below example from Platform of Trust, the API provider has decided to use snake case style in path parameter too {product_code} but it fits neatly to python code example. The same path parameter style is also in JS, cURL and java examples. In the print part 'raw_body' output name follows the convention in Python. The latter is not the same in other code examples.

import requests

response = requests.get(
    'https://api-sandbox.oftrust.net/products/v1/{product_code}'
)

print({
    'raw_body': response.json(),
    'status': response.status_code
})

Regarding the query parameters I stumbled upon an example where every param is prefixed with “_”. The idea is that it separates the parameters in url neatly, but that sounds a bit odd to me. Perhaps I’m so accustomed to not use underdash anywhere. This takes us to the second rule.

Rule 2: You pick one style for all and stick with it. Standardizing the naming increases the readability of the code. The readability of a program is related to its maintainability, and is thus a keyfactor in overall software quality. Typically, maintenance will consume over 70% of the total lifecycle cost of a software product (“Learning a Metric for Code Readability”).

Consistency lowers the learning curve as well as it brings along predictability. Developer can realy on a pattern. Nothing is more annoying that shifting case style. Think about it. In one endpoint it’s camel case, in the next one it’s dash case and on the third one it’s snake case. Or even worse, same endpoint uses various styles in parameter names. What a mess!

Crash mode

GET /api/resource? 
    sort_by=title&
    sortOrder=asc&
    created_at=...

Consistent mode

GET /api/resource? 
    sort_by=title&
    sort_order=asc&
    created_at=...

What about responses?

In response body you should follow the file format rules and conventions. If your API returns JSON which is nowadays common with REST APIs, it should use camel case like in the below example ("productCode", "dataContext", "parameterContext"…):


{
  "@context": "<context URL>",
  "@type": "Product",
  "@id": "<URL to the product resource>",
  "productCode": "<the product code>",
  "dataContext": "<data context URL>",
  "parameterContext": "<parameter context URL>",
  "translatorUrl": "<translator URL>",
  "name": "<product name>",
  "organizationPublicKeys": [
    {
      "url": "<public key URL>",
      "type": "<public key type>"
    }
  ],
  "description": "<product description>",
  "imageUrl": "<image URL>"
}

If your API returns XML it seems that it’s up to you as long as you follow the XML naming rules:

XML Schema seems to be lower camelCase. So for example all these would be valid:

<firstname> // All letters lower case
<FIRSTNAME> // All letters upper case
<first_name> // snake case/ underscore
<FirstName> // Pascal case
<firstName> // (lower) camel Case 

But again same rule as above applies here: pick one style and be consistent!

What about research?

Above was some pragmatic advises on the topic and empirical quotes from developers. What does research say about the subject? As I often do with articles in the series I try to find time to find fact based evidence from scientific articles. This time I found 2 interesting articles.

According to Bonita Sharif and Jonathan I. Maletic on average, camel-cased identifiers take 20% longer to read than underscored identifiers. Also Binkley et al. did similar research and found out that camel-cased identifiers take 13.5% longer.

There is a larger time difference between experts and novices with respect to underscored identifiers (364ms), whereas the difference is less for camel-cased identifiers. Also the difference in time between identifiers styles within experts is much less compared to the difference for the novice developers. This implies that experts are not affected as much as novices by the identifier style used.

When other factors are taken into account it becomes evident that the camel case style leads to better all around performance once a developer is trained on this style. It seems that no training is necessary to accurately recognize an identifier written in the camel case style, but training is required to quickly recognize such an identifier. Therefore, there is empirical evidence that supports the move towards camel casing in terms of accuracy and time. Binkley et al.


Some more to read from 100 Days DX