badges / badges/shields

snake_case vs camelCase URL query params

Open
#10,804 12 comments 0 reactions 0 assignees View on GitHub
developer-experience
Dominant language
JavaScript
Stars
27.2k
Forks
5.6k
Avg merge
1d 8h
Merged PRs (30d)
46

Description

Over the last 10+ years we have accumulated a lot of code written by a lot of different people.
In general, I think we've done a reasonable job of enforcing relatively consistent code styles and naming conventions, via documentation and/or lint rules, but there are obviously some exceptions.

One significant "blind spot" where we have a lot of variance is whether we use `snake_case` or `camelCase` URL query params.

There's a bunch of places where we are using camelCase. For example:

https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/maven-metadata/maven-metadata.service.js#L7-L11
https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/pypi/pypi-base.js#L23-L25
https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/nexus/nexus.service.js#L51-L57

and a bunch of places where we are using snake_case. For example:

https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/vpm/vpm-version.service.js#L6-L9
https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/gitea/gitea-last-commit.service.js#L26-L32
https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/website-status.js#L16-L21

I think the other day we acquired the first case where we have one of each next to each other on the same service :facepalm:

https://github.com/badges/shields/blob/41d072e1c93e997e8ac5f9c31cb763e351800bdb/services/matrix/matrix.service.js#L12-L17

I have not counted exactly, but roughly speaking we have about half and half.

The standard params that apply to all badges are all camelCase: `labelColor`, `logoColor`, `logoSize`

I think we've at least managed to avoid having any params that use `snake-case` 🤞 but maybe somewhere in the codebase there is an example :grimacing:

There are a couple of ways we can change the names of query params without making a breaking change. One way we can do it is with redirects. Another would be to write the `queryParamSchema`s to accept both formats but only document one for the services where we want to fix this. Having got to the stage where we have hundreds of service integrations, this is going to be quite difficult to unpick, and I wouldn't want to do it all at once. It would be nice to gradually work towards fixing this though.

I suggest we:

1. Pick one or the other
2. Document it
3. Make some kind of a lint/danger rule to catch this
4. At least get to a stage where everything we add from now onwards matches this convention
5. Gradually bring services into line with the convention

Given:

1. We use camelCase for variable names (which makes translating URL query params straight to correctly named variables easier)
2. The standard params that apply to all badges are all camelCase: `labelColor`, `logoColor`, `logoSize`

I'm gong to suggest we standardise on camelCase, but I also feel like there is a reason why we used snake_case in a lot of cases, and I can't remember what it is.

Contributor guide

Open the contributing guide

Research direction

Start by comparing the cited service files, including maven-metadata.service.js, pypi-base.js, matrix.service.js, and the snake_case examples, then review the queryParamSchema references and discussion. Decide the URL query-parameter convention and compatibility approach before defining the documentation and lint/Danger rule; done means new services are checked consistently and a gradual migration path is recorded.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.