Single document for explanations and decisions

[marktani]

I recently came across two use cases that would both be solved by a central document to give space for explanations and background information for decisions.

1. In-line comments

For a boilerplate, in-line comments are a bit annoying. They should be kept out of code, such as here:

const db = new Prisma({
  typeDefs: 'src/generated/prisma.graphql', // the auto-generated GraphQL schema of the Prisma API
  endpoint: process.env.PRISMA_ENDPOINT, // the endpoint of the Prisma API (value set in `.env`)
  debug: true, // log all GraphQL queries & mutations sent to the Prisma API
  // secret: process.env.PRISMA_SECRET, // only needed if specified in `database/prisma.yml` (value set in `.env`)
}

2. Production best practice vs. Easily getting started

Same code snippet, different context:

const db = new Prisma({
  typeDefs: 'src/generated/prisma.graphql', // the auto-generated GraphQL schema of the Prisma API
  endpoint: process.env.PRISMA_ENDPOINT, // the endpoint of the Prisma API (value set in `.env`)
  debug: true, // log all GraphQL queries & mutations sent to the Prisma API
  // secret: process.env.PRISMA_SECRET, // only needed if specified in `database/prisma.yml` (value set in `.env`)
}

secret is commented out, which allows for an easier getting started experience. However, in production I certainly do want to enable secret. This decision needs to be clearly documented, to avoid confusion.

I suggest to collect further use cases here, which can already lead as a first version of such a document 🙂