From 87fa753d2ccaf01cb3f770783bb9c5780e3909a1 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Thu, 26 Sep 2024 15:34:09 -0500 Subject: [PATCH] candid deprecated fields best practices --- .../candid/candid-concepts.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx b/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx index ecfd1944f0..13da12c298 100644 --- a/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx +++ b/docs/developer-docs/smart-contracts/candid/candid-concepts.mdx @@ -305,6 +305,8 @@ Regardless of the host language you use, it is important to know the mapping bet ## Best practices +### Use descriptive type names + It is recommended to use Candid records with descriptive names for types: ```candid @@ -319,3 +321,24 @@ type Recycler = nick: text; }; ``` + +### Deprecating fields + +To deprecate a Candid field, you can update the field's type to `opt empty`, indicating the field is not used: + +``` +record { + first_name : text; middle_name : opt empty; second_name : text; score : nat; country : text +} +``` + +However, it is best practice to mark a field as `reserved` to prevent future developers from using the field in an unexpected manner: + +``` +record { + first_name : text; middle_name : reserved; second_name : text; score : nat; country : text +} +``` + +For more information, refer to the blog post on [Candid for engineers](https://mmapped.blog/posts/20-candid-for-engineers#faq). +