From 8c5384316241248b32a5f5eef73811c9ab23dd19 Mon Sep 17 00:00:00 2001 From: Jeff Bezanson Date: Fri, 7 Sep 2018 13:39:14 -0400 Subject: [PATCH] stronger warnings about changing constants in help and docs (#28711) [ci skip] (cherry picked from commit 4b103ef33da6f3e66fc5708ee78f6fe37b0c6f36) --- base/docs/basedocs.jl | 18 ++++++++++-------- doc/src/manual/variables-and-scoping.md | 7 +++++-- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 062a9e554aa9a..4c12bf68d80b5 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -260,7 +260,7 @@ kw"'" """ const -`const` is used to declare global variables which are also constant. In almost all code +`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. @@ -275,15 +275,17 @@ const y, z = 7, 11 Note that `const` only applies to one `=` operation, therefore `const x = y = 1` declares `x` to be constant but not `y`. On the other hand, `const x = const y = 1` -declares both `x` and `y` as constants. +declares both `x` and `y` constant. -Note that "constant-ness" is not enforced inside containers, so if `x` is an array or -dictionary (for example) you can still add and remove elements. +Note that "constant-ness" does not extend into mutable containers; only the +association between a variable and its value is constant. +If `x` is an array or dictionary (for example) you can still modify, add, or remove elements. -Technically, you can even redefine `const` variables, although this will generate a -warning from the compiler. The only strict requirement is that the *type* of the -variable does not change, which is why `const` variables are much faster than regular -globals. +In some cases changing the value of a `const` variable gives a warning instead of +an error. +However, this can produce unpredictable behavior or corrupt the state of your program, +and so should be avoided. +This feature is intended only for convenience during interactive use. """ kw"const" diff --git a/doc/src/manual/variables-and-scoping.md b/doc/src/manual/variables-and-scoping.md index 47098fe0f9899..82d84f289ad4d 100644 --- a/doc/src/manual/variables-and-scoping.md +++ b/doc/src/manual/variables-and-scoping.md @@ -555,8 +555,11 @@ WARNING: redefining constant a 1 ``` -Note that although possible, changing the value of a variable that is declared as constant -is strongly discouraged. For instance, if a method references a constant and is already +Note that although sometimes possible, changing the value of a `const` variable +is strongly discouraged, and is intended only for convenience during +interactive use. +Changing constants can cause various problems or unexpected behaviors. +For instance, if a method references a constant and is already compiled before the constant is changed then it might keep using the old value: ```jldoctest julia> const x = 1