I am designing a new YAML file, and I want to use the most standard style of naming. Which is it?
kebab-case?
- job-name:
...
snake_case?
- job_name:
...
CamelCase?
- jobName:
...
I am designing a new YAML file, and I want to use the most standard style of naming. Which is it?
kebab-case?
- job-name:
...
snake_case?
- job_name:
...
CamelCase?
- jobName:
...
Use the standard dictated by the surrounding software.
For example, in my current project the YAML file contains default values for Python attributes. Since the names used in YAML appear in the associated Python API, it is clear that on this particular project, the YAML names should obey the Python lower_case_with_underscores
naming convention per PEP-8.
My next project might have a different prevailing naming convention, in which case I will use that in the associated YAML files.
yaml
name start with an underscore? like, _jobname__
more precisely, I need this one, __version__
Kubernetes using camelCase: https://kubernetes.io/docs/user-guide/jobs/
apiVersion
, restartPolicy
CircleCI using snake_case: https://circleci.com/docs/1.0/configuration/
working_directory
restore_cache
, store_artifacts
Jenkins with dash-case: https://github.com/jenkinsci/yaml-project-plugin/blob/master/samples/google-cloud-storage/.jenkins.yaml
stapler-class
So it looks like projects and teams use their own conventions and there is no one definite standard.
snake_case
and kebab-case
. Maybe it was not the case at the time when the answer was first posted, but it is the case now. GitHub Actions (one of the newer yaml based ci services) uses kebab-case
(at least for all major config options).
Commented
Jun 21, 2020 at 7:49
A less popular opinion derived from years of experience:
Obviously stick to the convention but IMHO follow the one that is established in your project's YML files and not the one that comes with its dependencies. I dare to say naming convention depends on too many factors to give a definitive answer or even try to describe a good practice other than "have some", so do what's most sensible to you and your team.
Libraries might change over time which leads to multiple naming conventions in one config more often than any sane programmer would like - you can't do much about it unless you want to introduce (and later maintain) a whole new abstraction layer dedicated to just that: keeping the parameter naming convention pristine.
A one example of why you would want a different naming convention in your configs vs. configs that came with the dependencies is searchability, e.g. if all dependencies use a parameter named request_id
, naming yours request-id
or requestId
will make it distinct and easily searchable while not hurting how descriptive the name is.
Also, it sometimes makes sense to have multiple parameters with the same name nested in different namespaces. In that case it might be justified to invent a whole new naming convention based on some existing ones, e.g.:
order.request-id.format
andnotification.request-id.format
While it probably isn't necessary for your IDE to differentiate between the two (as it's able to index parameters within the namespace) you might consider doing so anyway as a courtesy for your peers - not only other developers who could use different IDEs but especially DevOps and admins who usually do use less specialized tools during maintenance, migrations and deployment.
Finally, another good point raised by one of my colleagues is that distinctive parameter names can be easily converted into a different convention with something as simple as one awk
command. Doing so the other way around is obviously possible but by an order of magnitude more complicated which often spawns debates in the KISS advocates community about what it really means to "keep it simple stupid".