search

clarity-lang / book

Clarity of Mind is both an introductory as well as a reference book for the Clarity smart contract language.
http://book.clarity-lang.org
Creative Commons Attribution Share Alike 4.0 International
70 stars 49 forks source link

Document `(let ..)` in the book #20

Closed getify closed 1 year ago

getify commented 2 years ago

As I was reading this book, I was really missing coverage of what seems like a very important core/101 kind of feature: the let function. Unless I missed it, I don't think it's ever covered formally until it just shows up in a code-example under one of the Flow-Control pages (more than halfway thru the book).

In fact, TBH, since I'm not super well-versed in lisps, even referring to let as a function was unnatural to me, as it seems more like a keyword or core language feature. I kept thinking, "surely there's a way for me to create function-local variables, right!?! Right!?" As such, I didn't even think to look for it under "Functions" on the stacks-co language docs.

I think it would make sense for this book to call this kind of thing out. Here's 3 places I think it makes sense:

  1. In the "Clarity Basics" section, it could talk a bit more about s-expressions with function names (like let) work, and perhaps even a bit about why some of them require their arguments to be in sub ( ) parens sets... like let ( (..) (..) ) .. ) and all that. Being not super familiar with lisps, knowing when I need ( .. ) is the biggest thing I'm tripping on while learning.

  2. In "Storing Data" section, a mention should be made that "function local variables" (with (let .. )) is a fourth place to store data (in addition to the 3 "Constants", "Variables", and "Maps")

  3. In "Functions" page, after "Function Body" sub-section, the (let ..) should be covered.

I think it could be covered in all 3 of these places and that would improve the book. If agreed, I'd be happy to send in a PR for such.

MarvinJanssen commented 2 years ago

Great feedback and you are right! Welcome to submit a PR.

As for point 2., the "storing data section specifically refers to methods that store persistent data on-chain so I feel let should not be mentioned there. Perhaps the language can be more clear.

getify commented 2 years ago

@MarvinJanssen

As a compromise, could "Storing Data" section simply have a note that says something like "Unlike (let ..) which is temporary and localized to a function, these storage methods are persistent and stored on chain." Or something like that?

MarvinJanssen commented 2 years ago

Sounds good to me!