const docstring gives over-eager advice

[adienes]

the docstring:

const is used to declare global variables whose values will not change. In almost all code (and particularly performance sensitive code) global variables should be declared constant in this way.

it may seem a bit too-obvious but I think the docs should emphasize more strongly here that a variable should only be declared const if it is actually constant. the wording "almost all code" is quite strong here and there might also want to be information here that it is not just about the value changing but about the non-reassignment

that is, I doubt this is a legal use of const even though the value never changes (...unless it is in fact legal?)

const x = 1

function foo()
    while rand() < 0.99
        global x = (rand(1:2:11)^2) % 4
        println(x)
    end
end

[adienes]

also fun fact this segfaults on nightly but not 1.11

[Keno]

Well, I think it is very much true that the mutable globals have limited utility in library code. In almost all cases you need something more specific like a thread or task local mutable global. I think the primary use case for mutable globals is the REPL.

[adienes]

fair. maybe "that will not be reassigned" is marginally better than "whose values will not change," but either way I suppose it gets the same message across.