# Comments in Starknet contracts

**URL:** <https://community.starknet.io/t/comments-in-starknet-contracts/304>\
**Category:** Starknet Technical Development\
**Tags:** cairo, conventions\
**Created:** [January 6, 2022, 10:40am UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304 "2022-01-06T10:40:00Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![princearora](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/princearora/32/176_2.png) [@princearora](https://community.starknet.io/u/princearora)\
**Post date:** [January 6, 2022, 10:40am UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/1 "2022-01-06T10:40:00Z")

</div>

Hi,

It would be nice to have a standardized format for comments which can be used for docs, frontend UX in dapps, block explorers etc. We can take inspiration from NatSpec for solidity and vyper.  
[https://docs.soliditylang.org/en/v0.8.11/natspec-format.html](https://docs.soliditylang.org/en/v0.8.11/natspec-format.html)

I do not have a strict solution to follow at this moment, but wanted to start this discussion. Like solidity, we can use something in this format:

```auto
# @notice Transfer `amount` tokens from caller to `recipient`
# @dev _transfer has all the checks and logic
# @param recipient The address to transfer to
# @param amount The amount to be transferred
# @return success If the transfer was successful or not
@external
func transfer{
        syscall_ptr : felt*, 
        pedersen_ptr : HashBuiltin*,
        range_check_ptr
    }(recipient: felt, amount: Uint256) -> (success: felt):
    let (sender) = get_caller_address()
    _transfer(sender, recipient, amount)

    # Cairo equivalent to 'return (true)'
    return (1)
end

```

---

<div class="post-metadata">

**Author:** ![fracek](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/fracek/32/23_2.png) [@fracek](https://community.starknet.io/u/fracek)\
**Post date:** [January 6, 2022, 12:07pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/2 "2022-01-06T12:07:13Z")

</div>

I agree with this and I just visited the forum to suggest exactly this!

I think natspec like solidity (epytext in python?) is quite easy to learn and I would use that over one of the many formats used in Python (numpy-style, google-style, sphinx-style).

In the future it would be nice for tools to display the documentation alongside functions (e.g. in the explorer or wallet)

---

<div class="post-metadata">

**Author:** ![Orland0x](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/orland0x/32/166_2.png) [@Orland0x](https://community.starknet.io/u/Orland0x)\
**Post date:** [June 6, 2022, 2:11pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/3 "2022-06-06T14:11:20Z")

</div>

I drafted a standard for this as an informational SIMP. I agree keeping it as consistent with natspec as possible is worthwhile.

## Simple Summary

A standard for writing comments in Cairo contracts.

Inspired by [Natspec](https://docs.soliditylang.org/en/v0.8.14/natspec-format.html) comments for Solidity.

## Abstract

The following standard provides a consistent way for Cairo contracts and their functionality to be documented. I propose that initially this should just be informational, however in future it could be integrated into the Cairo compiler to allow automated documentation generation.

## Motivation

A comment standard increases the readibility of contracts which makes it easier to ensure their correct functionality.

## Specification

All tags are optional. The following table explains the purpose of each tag and where it may be used.

| Tag | Description | Context |
| --- | --- | --- |
| @title | Description of the cairo file | header |
| @author | Name and contact details of the author(s) | header |
| @notice | Explain to an end user what this does | header, storage variable, function, event, interface |
| @Dev | Explain to a developer any extra details | header, storage variable, function, event, interface |
| @param | Documents a parameter | storage variable, function, event |
| @return | Documents a return variable | storage variable, function |

### Headers

A header comment is a comment block that can be placed at the top of each cairo file, immediately following the imports. The header contains general information about the contents of the file including a brief description and an author.

### Arrays

When working with arrays, @param and @return tags should only be applied to the pointer variable and not for the length. One can document the contents of the array in this single tag.

### Example Contract

```auto
# SPDX-License-Identifier: MIT
%lang starknet

from starkware.cairo.common.cairo_builtins import HashBuiltin
from starkware.starknet.common.syscalls import get_caller_address

#
# @title Simple Savings Account
# @author Vitalik Buterin - vitalik.buterin@ethereum.org
# @notice A contract to track users' savings in various pots
#

# @Dev Stores the balances of each pot
# @param address: Address of the user
# @param pot_index: Index of the pot
# @return amount: The amount stored
@storage_var
func balance(address : felt, pot_index : felt) -> (amount : felt):
end

# @Dev Updates a user's balance in a specified pot
# @param amount: Amount to increase the balance by
# @param pot_index: Index of the pot
@external
func increase_balance{syscall_ptr : felt*, pedersen_ptr : HashBuiltin*, range_check_ptr}(
    amount : felt, pot_index : felt
):
    let (address) = get_caller_address()
    let (current) = balance.read(address, pot_index)
    balance.write(address, pot_index, current + amount)
    return ()
end

```

Source: [SIMPs/SIMPS/simp-4.md at main · Orland0x/SIMPs · GitHub](https://github.com/Orland0x/SIMPs/blob/main/SIMPS/simp-4.md)

---

<div class="post-metadata">

**Author:** ![jag-lotus](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/jag-lotus/32/675_2.png) [@jag-lotus](https://community.starknet.io/u/jag-lotus)\
**Post date:** [June 7, 2022, 2:11pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/4 "2022-06-07T14:11:45Z")

</div>

I really like this convention.

Writing contracts and libs, I couldn’t settle on a specific docstyle. And I agree with @fracek, using this in-code doc would be awesome.

---

<div class="post-metadata">

**Author:** ![jag-lotus](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/jag-lotus/32/675_2.png) [@jag-lotus](https://community.starknet.io/u/jag-lotus)\
**Post date:** [June 9, 2022, 6:00pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/6 "2022-06-09T18:00:47Z")

</div>

Starting to use it I think it could be useful to also add implicit arguments and types

```auto
struct Structure:
    member m1: felt
    member m2: felt
end

# @dev Updates a user's balance in a specified pot
# @implicit syscall_ptr (felt*)
# @implicit pedersen_ptr (HashBuiltin*)
# @implicit range_check_ptr (felt)
# @param value (felt): A value to do something
# @param structure (Structure*): A pointer to a Structure
# @return res (Structure): A Structure which is not a pointer
@external
func useful_function{syscall_ptr : felt*, pedersen_ptr : HashBuiltin*, range_check_ptr}(
    value : felt, structure : Structure*
) -> (res : Structure):
    # code #
    return (res)
end

```

---

<div class="post-metadata">

**Author:** ![Orland0x](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/orland0x/32/166_2.png) [@Orland0x](https://community.starknet.io/u/Orland0x)\
**Post date:** [June 13, 2022, 9:58am UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/7 "2022-06-13T09:58:34Z")

</div>

> [@jag-lotus](#):
>
> Starting to use it I think it could be useful to also add implicit arguments and types
> 
> ```auto
> struct Structure:
> member m1: felt
> member m2: felt
> end
> 
> # @Dev Updates a user's balance in a specified pot
> # @implicit syscall_ptr (felt*)
> # @implicit pedersen_ptr (HashBuiltin*)
> # @implicit range_check_ptr (felt)
> # @param value (felt): A value to do something
> # @param structure (Structure*): A pointer to a Structure
> # @return res (Structure): A Structure which is not a pointer
> @external
> func useful_function{syscall_ptr : felt*, pedersen_ptr : HashBuiltin*, range_check_ptr}(
> value : felt, structure : Structure*
> ) -> (res : Structure):
> # code #
> return (res)
> end
> 
> ```

Documenting Implicit arguments would get very repetitive as the same few of them get passed to virtually every function. Also as they are implicit, I don’t see them as necessary for documenting functionality/usage.

Types are specified in the function arguments already so seems redundant to do so again in my opinion. Within the description of the parameter, one can add information about the type if deemed necessary.

---

<div class="post-metadata">

**Author:** ![jag-lotus](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/jag-lotus/32/675_2.png) [@jag-lotus](https://community.starknet.io/u/jag-lotus)\
**Post date:** [June 13, 2022, 11:37am UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/8 "2022-06-13T11:37:59Z")

</div>

Yeah, I agree I went a bit overboard with typing everything, we can definitely infer `felt` type by default.

Regarding implicit arguments, the idea behind was to have easy access to which implicit args are required (even though, as you said, they are usually the same 3 to 4 ones) and not have to go look into the library’s code everytime. But I guess an improved vscode extension could display the function implicit arguments without the need for them to be described in the docstring.

---

<div class="post-metadata">

**Author:** ![gaetbout](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/gaetbout/32/712_2.png) [@gaetbout](https://community.starknet.io/u/gaetbout)\
**Post date:** [June 17, 2022, 1:40pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/9 "2022-06-17T13:40:39Z")

</div>

Hey,  
Just made a pull request to put it in the cairo snippets:

> <https://github.com/starknet-edu/cairo-snippets/pull/1>

So that it’ll be more easy to make them 🙂

---

<div class="post-metadata">

**Author:** ![Orland0x](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/orland0x/32/166_2.png) [@Orland0x](https://community.starknet.io/u/Orland0x)\
**Post date:** [July 15, 2022, 10:25am UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/10 "2022-07-15T10:25:07Z")

</div>

The proposal was merged into the repo as [SIMP-4](https://github.com/CairOpen/SIMPs/blob/main/SIMPS/simp-4.md)

---

<div class="post-metadata">

**Author:** ![Orland0x](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/orland0x/32/166_2.png) [@Orland0x](https://community.starknet.io/u/Orland0x)\
**Post date:** [October 18, 2022, 3:21pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/11 "2022-10-18T15:21:02Z")

</div>

An amendment to the standard to be compatible with the StarkNet 0.10.0 release.

## Simple Summary

A standard for writing documentation comments in Cairo contracts.

Inspired by [Natspec](https://docs.soliditylang.org/en/v0.8.14/natspec-format.html) comments for Solidity.

## Abstract

The following standard provides a consistent way for Cairo contracts and their functionality to be documented. I propose that initially this should just be informational, however in future it could be integrated into the Cairo compiler to allow automated documentation generation.

## Motivation

A documentation comment standard increases the readability of contracts which makes it easier to ensure their correct functionality.

## Specification

All tags are optional. The following table explains the purpose of each tag and where it may be used. Three slashes (`///`) should be used to mark each documentation comment instead of the two (`//`) used for standard comments. For multi-line documentation comments, the tag should only be used on the first line and there should be no tabulation on latter lines.

| Tag | Description | Context |
| --- | --- | --- |
| @title | Description of the cairo file | header |
| @author | Name and contact details of the author(s) | header |
| @notice | Explain to an end user what this does | header, storage variable, function, event, interface |
| @Dev | Explain to a developer any extra details | header, storage variable, function, event, interface |
| @param | Documents a parameter | storage variable, function, event |
| @return | Documents a return variable | storage variable, function |

### Headers

A header comment is a comment block that can be placed at the top of each cairo file, immediately following the imports. The header contains general information about the contents of the file including a brief description and an author.

### Arrays

When working with arrays, @param and @return tags should only be applied to the pointer variable and not for the length. One can document the contents of the array in this single tag.

### Example Contract

```auto
// SPDX-License-Identifier: MIT

%lang starknet

from starkware.cairo.common.cairo_builtins import HashBuiltin
from starkware.starknet.common.syscalls import get_caller_address

///
/// @title Simple Savings Account
/// @author Vitalik Buterin - vitalik.buterin@ethereum.org
/// @notice A contract to track users' savings in various pots
///

/// @Dev Stores the balances of each pot
/// @param address Address of the user
/// @param pot_index Index of the pot
/// @return amount The amount stored
@storage_var
func balance(address : felt, pot_index : felt) -> (amount : felt):
end

/// @Dev Updates a user's balance in a specified pot
/// @param amount Amount to increase the balance by
/// @param pot_index Index of the pot
@external
func increase_balance{syscall_ptr : felt*, pedersen_ptr : HashBuiltin*, range_check_ptr}(
    amount : felt, pot_index : felt
):
    let (address) = get_caller_address()
    let (current) = balance.read(address, pot_index)
    balance.write(address, pot_index, current + amount)
    return ()
end

```

Source: [SIMPs/SIMPS/simp-4.md at main · Orland0x/SIMPs · GitHub](https://github.com/Orland0x/SIMPs/blob/main/SIMPS/simp-4.md)

---

<div class="post-metadata">

**Author:** ![xdshnik](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/xdshnik/32/1079_2.png) [@xdshnik](https://community.starknet.io/u/xdshnik)\
**Post date:** [October 30, 2022, 2:57pm UTC](https://community.starknet.io/t/comments-in-starknet-contracts/304/12 "2022-10-30T14:57:25Z")

</div>

wow i am glad to see you