DEV Community


Posted on


How to explain in GraphQL-esque

Explaining in GraphQL is easy. Write single line comments with #. Offer more verbosity in multi-line descriptions with bracketing """.

Single Line Comment

Start exactly with # to comment a simple single line.

# A snack may or may not be delicious.
type Snack {
  name: String!,
  delicious: Boolean!

Perfectly safe in a GraphQL schema.

Multi-Line Description

Bracket a multi-line comment with """. GraphQL schema tools are smart. Multi-line descriptions are useful to tools like Graphiql.

A shirt.
It is a really simple type.
type Shirt {
The size of the shirt, like small or medium.
The value depends on the language of the user.
  size: String!,
  threads: Int!,
  thickness: Float!

Also safe in a GraphQL schema.

Query Comment

A single line comment is safe in a query. A multi-line description is not.

  snack {
    # this comment is safe

Possible in a GraphQL query.

Lack of comments is like a pandemic

GraphQL is for people. I don't disagree with code clarity as documentation. Sometimes people who have nothing to do with code may read a GraphQL text block. It's shocking. Let's not forget that comments are fundamentally for our hyper connected readers. I don't know if there is a better way.

Oldest comments (0)

This post was made by a DEV Community Member

Image description
We are an active and inclusive community of over one million registered creators, developers, and tech enthusiasts.

Everyone is welcome to take part!

Create your account now