snake_case vs camelCase URL query params
- 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
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