From b2879e440838bdaa1405baeff5e943528bc6c210 Mon Sep 17 00:00:00 2001
From: Novus Nota <68142933+novusnota@users.noreply.github.com>
Date: Fri, 10 Jan 2025 09:56:36 +0100
Subject: [PATCH] feat(docs): explain how storage variables get updated

---
 CHANGELOG.md                             |  1 +
 docs/src/content/docs/book/contracts.mdx | 34 +++++++++++++++++++++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eaf53e5e6..7d145bb1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed links in Chinese translation: PR [#1206](https://github.com/tact-lang/tact/pull/1206)
 - Added a note on 255 being the maximum number of messages that can be sent during action phase: PR [#1237](https://github.com/tact-lang/tact/pull/1237)
 - Added onchain metadata creation for NFTs and Jettons to the cookbook: PR [#1236](https://github.com/tact-lang/tact/pull/1236)
+- Document how storage variables get updated in relation to the `init()` function: PR [#1310](https://github.com/tact-lang/tact/pull/1310)
 
 ### Release contributors
 
diff --git a/docs/src/content/docs/book/contracts.mdx b/docs/src/content/docs/book/contracts.mdx
index cacab40c2..f3b06cf1c 100644
--- a/docs/src/content/docs/book/contracts.mdx
+++ b/docs/src/content/docs/book/contracts.mdx
@@ -137,7 +137,7 @@ In addition to that, [`tact.config.json`](/book/config) may still be used in [Bl
 
 ### Persistent state variables {#variables}
 
-Contracts can define state variables that persist between contract calls. Contracts in TON [pay rent](https://docs.ton.org/develop/smart-contracts/fees#storage-fee) in proportion to the amount of persistent space they consume, so [compact representations via serialization](/book/integers#serialization) are encouraged.
+Contracts can define state variables that persist between contract calls, and thus commonly referred to as _storage_ variables. Contracts in TON [pay rent](https://docs.ton.org/develop/smart-contracts/fees#storage-fee) in proportion to the amount of persistent space they consume, so [compact representations via serialization](/book/integers#serialization) are encouraged.
 
 ```tact
 contract Example {
@@ -149,11 +149,25 @@ contract Example {
 }
 ```
 
-State variables must have a default value or initialized in [`init(){:tact}`](#init-function) function, that runs on deployment of the contract. The only exception is persistent state variables of type [`map<K, V>{:tact}`](/book/maps) since they are initialized empty by default.
+State variables must have a default value or be initialized in the [`init(){:tact}`](#init-function) function that runs once on deployment of the contract. The only exception are persistent state variables of type [`map<K, V>{:tact}`](/book/maps), since they are initialized empty by default.
+
+The default value of state variables is assigned before any values could be assigned in the [`init(){:tact}`](#init-function) function.
+
+```tact
+contract Example {
+    // persistent state variables
+    var1: Int = 0; // initialized with default value 0
+
+    // constructor function
+    init() {
+        self.var1 = 42; // overrides the default to 42
+    }
+}
+```
 
 :::note
 
-  Note, that Tact supports local, non-persistent-state variables too, see: [Variable declaration](/book/statements#let).
+  Tact supports local, non-persistent-state variables too, see: [Variable declaration](/book/statements#let).
 
 :::
 
@@ -211,6 +225,20 @@ contract Example {
 }
 ```
 
+The default value of [state variables](#variables) is assigned before any values could be assigned in the `init(){:tact}` function.
+
+```tact
+contract Example {
+    // persistent state variables
+    var1: Int = 0; // initialized with default value 0
+
+    // constructor function
+    init() {
+        self.var1 = 42; // overrides the default to 42
+    }
+}
+```
+
 If a contract doesn't have any persistent state variables, or they all have their default value specified, it may omit the `init(){:tact}` function declaration altogether. That's because unless explicitly declared, the empty `init(){:tact}` function is present by default in all contracts.
 
 The following is an example of a valid empty contract: