Comments

Comments are used by developers for themselves or other developers to provide insight into some functionality.

There are many ways to achieve the same outcome for a line of code however there are implementation tradeoffs to consider and a developer might be interested in knowing why the current approach has been chosen.

Moreover, it may not be immediately clear why, or what, some line of code is doing so it may be a good idea to add a comment summarizing the intent behind the implementation.

The following snippet looks at two items being documented using the comment syntax //.

• Item1 has poor comments that do not convey any meaningful information and it's better to not include them at all.
• Item2 has taken the approach of describing the context in order to provide meaning behind each field

// This is bad. It's repeating the names of the fields which can be easily read
pub struct Item1 {
    /// Identifier
    id: u64,
    /// Quantity
    quantity: u64,
}

// This is better. It conveys the context of what the fields are
pub struct Item2 {
    /// Unique identifier used to retrieve the item from a vector of items held in storage
    id: u64,
    /// The number of remaining items left in production
    quantity: u64,
}