# bash/doc-comments

> Checks that each shell function has a comment above it that says more than its name.

Checks that each shell function has a comment above it that says more than its name.

Part of the [`bash`](/reference/configurations/bash/) configuration, at the `all` [level](/start/concepts/#levels). It runs at the `commit` [stage](/start/concepts/#stage), per file. gspot runs this check itself.

## Why

Without a summary, the reader must trace the function in their head, and nobody trusts a vague one.

## What to do

Write “# name: what it does” above the function; when it carries doc sections, keep Globals, Arguments, Outputs, and Returns in that order.

## Example

`_quiet() { printf "%s\n" "Hello"; }` with no comment above it reports a finding. Add `# _quiet: prints a greeting.` on the line above.

## Turn it off

Turn it off for some files, with a reason:

```shell
gspot ignore bash/doc-comments --paths "<glob>" --reason "<why>"
```