---
description: What block comments are and how to use them.
title: Block comments
image: images/blockly_banner.png
---

# Block comments

Block comments allow users to add comments to a block. Like comments in a
text-based programming language, they do not affect a block's behavior. They are
added to generated code (including code generated by custom blocks) by the
standard language code generators.

![An if block with a
comment](/images/workspace-comments/block-comment.png)

## The comment icon

Users enter block comments with the comment icon's text editor.

By default, the comment icon is not displayed. There are two ways to display it:

- Call `Block.setCommentText` with a non-null string.
- Let the user display it by clicking "Add Comment" in the block's context
  menu.

To remove the comment icon:

- Call `Block.setCommentText` with a `null`.
- Let the user remove it by clicking "Remove Comment" in the block's context
  menu.

Note that "Add Comment" and "Remove Comment" are displayed in the context menu
only if:

- The block is [editable].
- The block is not collapsed.
- The [`comments` configuration option][config-option] is set to `true`. If
  you do not explicitly set this option, it defaults to `true` if the toolbox
  has categories, `false` otherwise.

## Work with block comments programmatically

To get a block comment:

```js
// Returns comment text or null if there is no comment.
myBlock.getCommentText();
```

To set a block comment:

```js
// Sets comment text and displays comment icon.
myBlock.setCommentText('My comment');
```

To delete a block comment:

```js
// Removes comment text and removes comment icon.
myBlock.setCommentText(null);
```

The ability to work with comments programmatically is not affected by the state
of the block (such as whether it is editable or collapsed) or the setting of the
`comments` configuration option.

[editable]: /guides/create-custom-blocks/define/block-state#editable-state
[config-option]: /guides/configure/configuration_struct#the-options-dictionary
