# Revisiting the Comment Standard: NatSpec or Rust **URL:** \ **Category:** Starknet Technical Development\ **Tags:** cairo, conventions\ **Created:** [August 1, 2023, 1:53pm UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009 "2023-08-01T13:53:25Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![andrew](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/andrew/32/208_2.png) [@andrew](https://community.starknet.io/u/andrew)\ **Post date:** [August 1, 2023, 1:53pm UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/1 "2023-08-01T13:53:25Z")
Since the initial SNIP-4 proposal, both the Starknet contract syntax and Cairo programming language have radically transformed. It therefore seems worth revisiting the comment/documentation standard. * * * [SNIP-4](https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-4.md) established a [NatSpec](https://docs.soliditylang.org/en/v0.8.11/natspec-format.html)-like documentation style for Cairo v0.TL;DR NatSpec uses tags in the comment block a la `@dev`, `@notice`, `@param`, etc. The new syntax of Cairo v1+ is in many ways a brand new language with a heavy Rust resemblance. Given the strong Rust influence on the language, it makes sense to me that Cairo should follow a Rust-like documentation approach. Rust’s doc style utilizes markdown in the comment block and does not use tags (see [here](https://doc.rust-lang.org/rust-by-example/meta/doc.html)). A few projects have already chosen Rust-like comments (at least as of this writing): - [Alexandria](https://github.com/keep-starknet-strange/alexandria). - [Dojo](https://github.com/dojoengine/dojo). - [Orion](https://github.com/gizatechxyz/orion). Meanwhile NatSpec is used with: - [SNIP-4](https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-4.md). - [SNIP-5](https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-5.md). - [Kakarot](https://github.com/kkrt-labs/kakarot/tree/main). - Highlighted example: [https://github.com/kkrt-labs/kakarot/blob/c04cb72f040e059dfa3a8dc4ca24c6a68083409b/src/utils/rlp.cairo#L26-L29](https://github.com/kkrt-labs/kakarot/blob/c04cb72f040e059dfa3a8dc4ca24c6a68083409b/src/utils/rlp.cairo#L26-L29) ## NatSpec or Rust? So what do you prefer? Stick with NatSpec? Move to Rust-like comments? Create Cairo’s own “DaddySpec” standard? Sound off! ---
**Author:** ![abdel.1559](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/abdel.1559/32/85849_2.png) [@abdel.1559](https://community.starknet.io/u/abdel.1559)\ **Post date:** [August 2, 2023, 4:34pm UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/2 "2023-08-02T16:34:48Z")
I am 100% for Rust like doc!!! I think we could even leverage cargo doc tooling maybe ---
**Author:** ![mkaput](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/mkaput/32/73385_2.png) [@mkaput](https://community.starknet.io/u/mkaput)\ **Post date:** [August 3, 2023, 1:49am UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/3 "2023-08-03T01:49:06Z")
This is definitely something we’ll welcome being built-into Scarb! Because I believe everyone would appreciate having `scarb doc` 🙂 ---
**Author:** ![0xHyoga](https://avatars.discourse-cdn.com/v4/letter/0/b2d939/32.png) [@0xHyoga](https://community.starknet.io/u/0xHyoga)\ **Post date:** [August 4, 2023, 2:15pm UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/4 "2023-08-04T14:15:03Z")
100% behind rust-like doc. It’d be great to have it built into Scarb too 🙂 ---
**Author:** ![ivpavici](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/ivpavici/32/662_2.png) [@ivpavici](https://community.starknet.io/u/ivpavici)\ **Post date:** [August 16, 2023, 6:53am UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/5 "2023-08-16T06:53:59Z")
+1 for Rust-like comments! ---
**Author:** ![martriay](https://dub1.discourse-cdn.com/flex005/user_avatar/community.starknet.io/martriay/32/25_2.png) [@martriay](https://community.starknet.io/u/martriay)\ **Post date:** [September 8, 2023, 9:33pm UTC](https://community.starknet.io/t/revisiting-the-comment-standard-natspec-or-rust/98009/6 "2023-09-08T21:33:59Z")
Great initiative and writeup! Really liked it 🙂 Some comments on the [SNIP-8 proposal](https://github.com/andrew-fleming/SNIPs/blob/comment-snip/SNIPS/snip-8.md): ## 1. Contract documentation > Contract documentation refers to an expositional overview of the contract. This may include a description of the contract itself and examples of use. Contract documentation may use the characters `//!` to communicate that it is contract documentation. This proposal recommends that contract documentation should start at the top of the file. Shouldn’t we focus on _modules_ instead of _contracts_? Especially with the upcoming components functionality. ## 2. SPDX license identifiers > This proposal recommends that every contract includes an SPDX license identifier. For visibility purposes, this proposal also recommends beginning the contract documentation with an SPDX license identifier (which is similar to the recommended Solidity source file layout). What’s the requirement level of is this recommendation as per [RFC2119](https://www.ietf.org/rfc/rfc2119.txt)? `SHOULD`? `OPTIONAL`? Either way, I’m unsure how tightly should we couple licensing and comment standardization. ## 3. Element documentation ````js #[starknet::contract] mod MyContract { #[storage] struct Storage {} /// Returns the sum minus one of `arg1` and `arg2`. /// `arg1` cannot be zero. /// /// # Panics /// /// This function will panic if `arg1` is `0`. /// /// # Examples /// /// ```rust /// let a: felt252 = 2; /// let b: felt252 = 3; /// let c: felt252 = sum_minus_one(a, b); /// assert(c + 1 == a + b, "Should equal a + b"); /// ``` #[external(v0)] fn sum_minus_one(arg1: felt252, arg2: felt252) -> felt252 { assert(arg1 != 0, "Cannot be zero"); let sum: felt252 = arg1 + arg2; // Subtract `1` from the sum sum - 1 } } ```` This is not a suggestion but a comment, I feel like the doc is very long and its beginning can get a bit far away of the function name (or any other element being documented). Is it worth adding a title to the doc section to aid the reader?