Add code comments

Co-authored-by: Ping Xie <[email protected]>

src/cluster_legacy.c

@@ -911,7 +911,18 @@ static void updateAnnouncedHumanNodename(clusterNode *node, char *new) {
 
 
 static void updateShardId(clusterNode *node, const char *shard_id) {
-    /* Shard id update of replica independently will corrupt the config file. */
+    /* Ensure replica shard IDs match their primary's to maintain cluster consistency.
+     *
+     * Shard ID updates must prioritize the primary, then propagate to replicas.
+     * This is critical due to the eventual consistency of shard IDs during cluster
+     * expansion. New replicas might replicate from a primary before fully
+     * synchronizing shard IDs with the rest of the cluster.
+     *
+     * Without this enforcement, a temporary inconsistency can arise where a
+     * replica's shard ID diverges from its primary's. This inconsistency is
+     * persisted in the primary's nodes.conf file. While this divergence will
+     * eventually resolve, if the primary crashes beforehand, it will enter a
+     * crash-restart loop due to the mismatch in its nodes.conf. */
     if (shard_id && nodeIsSlave(node) && memcmp(clusterNodeGetMaster(node)->shard_id, shard_id, CLUSTER_NAMELEN) != 0) {
         serverLog(
             LL_NOTICE,