Break "Methods and instance variables” into “Instance Variables” and “Instance Methods”

[andyfleming]

Related discussion with @RX14 on gitter

Andy Fleming @andyfleming 16:14

I say we break "Methods and instance variables” into “Instance Variables” and “Instance Methods”. Then we start with manual getters and setters, then introduce the shorthand and the property concept. It would be nice and clean. Then in the “Instance Methods” page, we can use the shorthand.

@RX14 16:14

hmm

i think "new, initialize and annlocate" should be merged into "methods and instance variables" somewhat too

that area of docs keeps coming up as a pain point

Andy Fleming @andyfleming 16:16

Yeah

allocate seems like an advanced topic that shouldn’t be mixed in with creation of class instances

(though a mention/link might be appropriate)

[andyfleming]

I wanted to start a discussion before opening a PR.

[andyfleming]

Related to https://github.com/crystal-lang/crystal-book/issues/14

[andyfleming]

Here's the general direction of what I'm thinking:

Current Outline

[page] new, initialize and allocate

• create an instance of a class by invoking new
• convoluted explanation of initialize
• code example with person class and creating two instances
• note referencing/linking to "global type inference algorithm"
• explanation of what happens behinds the scenes with initalize including notes about allocate

[page] Methods and instance variables

• simplifying our constructor
• adding a method to modify an instance variable (that "makes a person become older")
• method naming convention
• writing methods in separate class blocks (is this a best practice?)
• Explanation and example of method definition precedence
• Explanation of previous_def
  • seems advanced for this area
• How to initialize an instance variable outside of the initialize method

Proposed Outline

[page] Class and Instance Variables

• basic class definition and initialization
• define in initialize
  • code example
• define via argument of initialize
  • code example
• define in class body
  • code example
• define a class variable instead of an instance variable
  • code example showing two instances and accessing class and instance variables
• accessors
  • manual getters
  • manual setters
  • shorthand getter declaration
  • shorthand setter declaration
  • shorthand property declaration

[page] Class and Instance Methods

• basic method definition
  • method naming convention
• note about visibility and link to that doc

[page] Definition precedence

• writing methods in separate class blocks
• Explanation of previous_def

[andyfleming]

Also, it seems like there is too much concern about what functionality is via macros.

Users care first about how to accomplish their task at hand. Details of the technical implementation or intermediary mechanism is secondary.

[mverzilli]

👍 to the proposed outline. 👍 to hiding more implementation details at this point of the book. We can always disclose those at a later section focusing on the more advanced topic of macros.