# The manual's section on variable scope sucks

**URL:** <https://discourse.julialang.org/t/the-manuals-section-on-variable-scope-sucks/119522>\
**Category:** General Usage\
**Tags:** documentation, scope\
**Created:** [September 17, 2024, 8:03pm UTC](https://discourse.julialang.org/t/the-manuals-section-on-variable-scope-sucks/119522 "2024-09-17T20:03:43Z")\
**Posts on this page:** 1\
**Showing post:** 46

<div class="post-metadata">

**Author:** ![Nathan\_Boyer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nathan_boyer/32/14825_2.png) [@Nathan\_Boyer](https://discourse.julialang.org/u/Nathan_Boyer)\
**Post date:** [October 17, 2024, 3:03pm UTC](https://discourse.julialang.org/t/the-manuals-section-on-variable-scope-sucks/119522/46 "2024-10-17T15:03:23Z")

</div>

> [@Tamas\_Papp](#):
>
> However, now the chapter is full of well-meaning additions and side points like this which makes it hard to read.

Agreed; eliminate them if you can. I’d prefer a rewrite where complexity is added as you go down the page, so a user can read as far as they are comfortable. A user should not need to understand every nuanced scope detail to run their first loop.

> [@Tamas\_Papp](#):
>
> Your example runs fine for me, I must be missing something.

It runs fine in a `let` block or some other local scope, where the output is

```julia
0
10

```

But if the outer scope is global, I get one of the following:

```julia
0
0
0
...

```

```julia
10
10
10
...

```

```julia
ERROR: LoadError: UndefVarError: `i` not defined in local scope
Suggestion: check for an assignment to a local variable that shadows a global of the same name.

```

I emphasize the `while` case because I think this is where users are most likely to encounter their first scoping problem. I wrote loops like this all the time without thinking about it in Matlab.

> [@sadish-d](#):
>
> But to me, this is secondary to accuracy and completeness.

> [@lmiq](#):
>
> However, I admit that the necessity of sticking with a precise language in the manual restricts, a lot, it’s accessibility.

@sadish-d’s main complaint seems to be that the scope manual is imprecise. My main complaint is that the scope manual is unapproachable. These are somewhat competing design philosophies. In a perfect world you would achieve both simultaneously, but you may need to focus different sections one way or another.

> [@woclass](#):
>
> Then we could add a new “How-to” parts where we teach the user how to fix various errors related to variable scopes.

> [@lmiq](#):
>
> That’s why I like opinionated blog posts.

That said, [I feel strongly both can co-exist in the same manual](https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942). My personal preference would be to switch the manual organization from:

```raw
# Topic A
if global
  if script
    rules
  end
  if interactive
    rules
  end
else
  rules
end

# Topic B
if ...

```

to

```raw
# Usually
## Explaination
Julia users are encouraged to write code inside functions where the following scoping rules apply.
## Topic A
rules
## Topic B
rules

# Scoping Changes for Global Variables
## Explaination
global variables behave differently because ... (across files, compiler performance)
## Topic A
rule changes
## Topic B
rule changes

# Scoping Changes for Interactive Sessions
## Explaination
the REPL and notebooks behave differently because ... (convenience trumps performance)
## Topic A
rule changes
## Topic B
rule changes

```

I think this gives you the best shot of being precise and accessible simultaneously.

---

_[View the full topic](https://discourse.julialang.org/t/the-manuals-section-on-variable-scope-sucks/119522)._