I’ve been working on TLS lately. The specs, the APIs, and even the docs make me feel dumb. Why is this so hard?! I struggle when it takes 2 hours to do something that should take 20 minutes.
One thing that makes TLS difficult is the jargon and acronyms. To create a certificate you’re gonna encounter:
- ASN.1
- CA
- CN
- DER
- EC
- PEM
- PKCS 8
- RSA
- SAN
- X.509
Which ones do you recognize?
It slows me down when a concept has multiple names. Here’s one from a codebase that’s usually okay:
fun addSubjectAlternativeName(altName: String) {
altNames += altName
}
fun commonName(cn: String) {
this.cn = cn
}The functions use subjectAlternativeName and commonName but the parameters call these altNames and cn. Do more certificate work and you’ll also see san, which stands for Subject Alternative Name.
One thing? One name.
I am much happier when each concept has exactly one name. I don’t want to wonder whether I can pass a commonName to a function that wants a CN.
I see this problem everywhere. Sometimes within even small projects I puzzle, “is this distinction between file and path deliberate?” “Are bitmap and image different somehow?” “are users and accounts interchangeable?”
If there is a distinction, use distinct names.
But if there isn’t, please don’t. Complexity grows with the number of distinct concepts, and it’s a mistake to create unnecessary complexity.