Notes on Gherkin

A language I encountered while researching how to write comments in code

目次

How to write code comments is quite challenging. I've been researching this topic recently, and I'd like to introduce Gherkin, which I came across during my research.

What is Gherkin?

It's part of Cucumber, a Ruby test framework. Cucumber is oriented toward Behaviour-Driven Development. Gherkin seems to be a dedicated language for describing behavior. In other words, it specializes in describing how code behaves. Therefore, I thought it would be effective to extract just this language and repurpose it elsewhere.

Example

Here's an example of Gherkin syntax (apologies for any display issues as CSS is being adjusted):

Feature: Guess the word
  # The first example has two steps
  Scenario: Maker starts a game
    When the Maker starts a game
    Then the Maker waits for a Breaker to join
  # The second example has three steps
  Scenario: Breaker joins a game
    Given the Maker has started a game with the word "silky"
    When the Breaker joins the Maker's game
    Then the Breaker must guess a word with 5 characters

-- Gherkin Reference

The terms that appear here, such as Feature, Scenario, When, Then, are reserved words. As you can see, it's very concise. Please refer to the reference for specific syntax. However, if you're just repurposing it as a format for comments, you don't need to be too strict about it.

First, you declare a feature, then define what scenarios, under what conditions, lead to what results. Generally, it's good practice to write summaries that highlight these key points. But it's not common to consciously adhere to such a rigid format when writing. With Gherkin, the format is structured as grammar, so there's no room for confusion.

Conclusion

Writing text (from scratch), not just comments, can sometimes be more difficult than writing code. Following a certain framework or format like this seems to reduce the cognitive load. Recently, Google's Technical Writing course has gained attention, and beyond Gherkin, having appropriate frameworks for different fields can be a powerful tool. I think I'll try using it for a while.