Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

manual/workflow-tips: simplify the basic workflow (& explain _why_ we put code in a module) #48319

Merged
merged 2 commits into from
Oct 30, 2023

Conversation

tfiers
Copy link
Contributor

@tfiers tfiers commented Jan 17, 2023

I came upon this piece of documentation again after seeing this popular post by @bkamins: https://discourse.julialang.org/t/how-to-clear-variables-and-or-whole-work-space/10149/21?u=tfiers

("How to clear variables and/or whole work space?" → "Work in a module")

This small addendum to the Worfklow Tips section of the manual answers "but why should I bother making that module";
basically putting the gist of that discourse thread in the documentation, where more people might see it

@tfiers
Copy link
Contributor Author

tfiers commented Jan 17, 2023

suggestions for other wording welcome ("the Main module of the REPL" might not be something accurate, e.g.)

@brenhinkeller brenhinkeller added the docs This change adds or pertains to documentation label Jan 18, 2023
Comment on lines 29 to 32
The key here is to encapsulate the code in a module.
If it were not so, and the code was ran directly in the `Main` module of the REPL,
you would not be able to remove methods or edit `struct` definitions, without restarting Julia.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The key here is to encapsulate the code in a module.
If it were not so, and the code was ran directly in the `Main` module of the REPL,
you would not be able to remove methods or edit `struct` definitions, without restarting Julia.
The key here is to encapsulate the code in a module.
This makes the global state more isolated, so that it is not affected by prior content in the `Main` module of the REPL,
or methods and `struct` definitions added before.
This reduces the need to restart Julia in this workflow.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(changed to word this only in the positive, and to mention another benefit of this workflow tip)

Copy link
Contributor Author

@tfiers tfiers Jan 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review and suggestion :)

The isolation from previous REPL commands is indeed another benefit.
Maybe confusing for new users that "the global state" refers to the state inside the module?

Does using a module reduce the need for restarting Julia, or (virtually) eliminate it?

I'll tag the original author of this section (4b51aef), @twadleigh, to ask them what they think.

Copy link
Contributor Author

@tfiers tfiers Jan 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually this edit changes what I meant: I think that in an "efficient interactive workflow", which this guide is about, the main advantage of a module is not having to restart Julia when editing structs or removing methods.

@tfiers
Copy link
Contributor Author

tfiers commented Jan 21, 2023

Thinking about this whole section more, I think it can be simplified further:

  • why even need a separate test file? Just write it in the same file, underneath the module. Or even inside the module?
  • why both the import and using lines. This is a place to be opinionated (i.e. pick using)

@tfiers tfiers changed the title manual/workflow-tips: explain _why_ we put code in a module manual/workflow-tips: simplify the basic workflow (& explain _why_ we put code in a module) Jan 21, 2023
@tfiers
Copy link
Contributor Author

tfiers commented Jan 21, 2023

I rewrote (simplified) the entire section.
Adding the original author @twadleigh as additional reviewer, and @KristofferC, who previously (re-)simplified this section (#30194)

Very open to new suggestions, this is a draft.

Edit: (seems like I can't add reviewers). Input welcome anyway

@vtjnash vtjnash merged commit 96147bb into JuliaLang:master Oct 30, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants