Documentation

Es importante tomarse el tiempo para documentar su código. Ayudará a los desarrolladores y usuarios a comprender el contrato y sus funcionalidades.

En Cairo, puedes agregar comentarios con //.

Best Practices:

Since Cairo 1, the community has adopted a Rust-like documentation style.

Contract Interface:

In smart contracts, you will often have a trait that defines the contract's interface (with #[starknet::interface]). This is the perfect place to include detailed documentation explaining the purpose and functionality of the contract entry points. You can follow this template:

#[starknet::interface]
trait IContract<TContractState> {
    /// High-level description of the function
    ///
    /// # Arguments
    ///
    /// * `arg_1` - Description of the argument
    /// * `arg_n` - ...
    ///
    /// # Returns
    ///
    /// High-level description of the return value
    fn do_something(ref self: TContractState, arg_1: T_arg_1) -> T_return;
}

Tenga en cuenta que esto no debe describir los detalles de implementación de la función, sino más bien el propósito de high-level y la funcionalidad del contrato desde la perspectiva de un usuario.

Implementation Details:

Al escribir la lógica del contrato, puede agregar comentarios para describir los detalles técnicos de implementación de las funciones.

Avoid over-commenting: Comments should provide additional value and clarity.