/
Naming Things

Naming Things

Jul 14, 2017

“There are only two hard things in Computer Science: cache invalidation and naming things”

Phil Karlton


When writing software, we often find ourselves needing to name things: files, classes, variables, GitHub repositories, Python packages, etc.  As noted above, doing this well is hard; a programmer can easily pick a name that solves the immediate problem, but many such well-intended choices can be confusing or misleading to other people coming from different contexts (or after some time has passed, even to the programmer who named it).  A comprehensive set of guidelines on how to name things well could fill an entire book, but here are some guidelines that are likely to be useful to developers at edX.

  • Python Naming Conventions - As stated in the edX Python Style Guide, we follow PEP 8 in this context

  • JavaScript Naming Conventions - As stated in the edX JavaScript Style Guide, we follow the Airbnb JavaScript Style Guide in this context

  • IT's Best Practices for Naming - This has some good general guidelines, and some specific considerations for JIRA artifacts and such.

  • Package Names - If the project is edX specific, use the "edx-" prefix. Don't use it if it the scope is more general (for example tools like "bok-choy", "diff-cover", etc.)  Earlier discussion of this topic: Standards for Engineering, Coding, Repository

  • Repository Names - The name of our GitHub organization is "edx", so it's redundant to add "edx-" to the package name as well.  It's OK if this means that a repository without "edx-" in its name produces a Python package which does have it.