Pharo with Style

https://github.com/squarebracketassociates/booklet-pharowithstyle
Admin
This book focuses on code communication and helps developers write code that follows Pharo coding...
Tokens:40,532
Snippets:269
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Executable Comments with `>>>`

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Utilize executable examples in comments using the `>>>` message for clarity and automated verification. This ensures documentation stays synchronized with code.

```Pharo Smalltalk
```type=preferProtoObject >> ifNil: nilBlock ifNotNil: ifNotNilBlock
	"If the receiver is not nil, pass it as argument to the ifNotNilBlock block
	 else execute the nilBlock block "
	"(nil ifNil: [42] ifNotNil: [:o | o + 3 ] ) >>> 42"
	"(3 ifNil: [42] ifNotNil: [:o | o + 3 ]) >>> 6"
		^ ifNotNilBlock cull: self```
```

```Pharo Smalltalk
```type=preferObject >> split: aSequenceableCollection
	"Split the argument using the receiver as a separator."
	"optimized version for single delimiters"
	"($/ split: '/foo/bar')>>>#('' 'foo' 'bar') asOrderedCollection"
	"([:c| c isSeparator] split: 'aa bb cc dd') >>> #('aa' 'bb' 'cc' 'dd') asOrderedCollection"
			|
	result
|
	result := OrderedCollection new: (aSequenceableCollection size / 2) asInteger.
	self split: aSequenceableCollection do: [ :item |
		result add: item ].
	^ result```
```

--------------------------------

### Method Comment Guidelines

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Method comments should provide comprehensive usage information, including purpose, parameters, return values, side effects, and examples, without requiring access to the source code.

```Pharo Smalltalk
```type=preferCollection >> asCommaString    "Return collection printed as 'a, b, c' "    "#('a' 'b' 'c') asCommaString >>> 'a, b, c'"        ^ String streamContents: [:s | self asStringOn: s delimiter: ', ' ]```
```

--------------------------------

### Automatic Object Initialization with 'initialize'

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Demonstrates how to use the `initialize` method for automatic object state setup. When `new` is called, `initialize` is automatically invoked. This ensures that objects are created with a defined default state, preventing potential logic errors if clients forget to set initial values. A test case is provided to verify the default initialization.

```Pharo
Game new turn: 0

preferGame >> initialize
	super initialize.
	turn := 0.

GameTest >> testDefaultInitialization
	self assert: Game new turn equals: 0
```

--------------------------------

### Almond.js Optimization Example

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.md

Shows the command-line usage for the Almond.js optimizer to configure module names and paths when building Highlight.js for AMD environments.

```bash
r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
```

--------------------------------

### Manual Initialization with jQuery

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.ru.md

An example of manually initializing Highlight.js using jQuery. It iterates over all 'pre code' elements and applies highlighting to each block.

```javascript
$(document).ready(function() {
  $('pre code').each(function(i, block) {
    hljs.highlightBlock(block);
  });
});
```

--------------------------------

### Accessor Comment Example

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Accessors typically only need a comment explaining the purpose of the instance variable they manage.

```Pharo Smalltalk
```day	"Answer number of days (an instance of Integer) from 	the receiver to January 1, 1901."	^ day```
```

--------------------------------

### Highlight Control Flow with Indentation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This guideline promotes using indentation to help readers understand the control flow logic of the code. It provides examples of preferred and non-preferred indentation styles for methods related to size and depth.

```Smalltalk
type=prefersize	"Returns size of a tree - number of nodes in a tree"
	self root isNil 
		ifTrue: [ ^0 ].
	^ self size: self root
```

```Smalltalk
type=notsize	"Returns size of a tree - number of nodes in a tree"
	self root isNil 
	ifTrue: [ ^0 ].
	^self size: self root.
```

```Smalltalk
type=notdepth:aNode	"Returns depth of a tree starting from the given node"
	| leftDepth rightDepth |
	leftDepth := -1.
	aNode leftChild isNotNil 
		ifTrue: [ leftDepth := self depth: aNode leftChild ].
	rightDepth := -1.
	aNode rightChild isNotNil 
		ifTrue: [ rightDepth := self depth: aNode rightChild ].
		( leftDepth > rightDepth )
		ifTrue: [ ^ (1 + leftDepth) ]
		ifFalse: [^ (1 + rightDepth ) ].
```

--------------------------------

### Method Naming: Short Sentences

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Advises choosing method names that allow the message expression to be read as a sentence.

```Pharo
type=prefer
FileDescriptor seekTo: word from: self position
```

```Pharo
type=not
FileDescriptor lseek: word at: self position
```

--------------------------------

### Basic Highlight.js Setup

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.ru.md

This snippet shows the minimum required HTML and JavaScript to include Highlight.js on a webpage. It links to the CSS styles and the JavaScript library, then initializes highlighting on page load.

```html
<link rel="stylesheet" href="/path/to/styles/default.css">
<script src="/path/to/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
```

--------------------------------

### Prefer Tabs for Indentation and Spaces for Reading

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This guideline emphasizes using tabs for indentation and spaces for separating elements to improve code readability. It contrasts preferred and non-preferred examples.

```Smalltalk
type=preferstemSymbolFrom: aName	| stemmer symbol |
	stemmer := SymbolStemmer new.	symbol := stemmer performCrawling: aName.	^ symbol
```

```Smalltalk
type=notstemSymbolFrom: aName	|stemmer symbol|
      stemmer:=SymbolStemmer new.
   symbol:=stemmer performCrawling: aName.
   ^symbol
```

--------------------------------

### Pharo Recursive Depth Calculation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Provides an example of calculating tree depth, demonstrating preferred versus non-preferred parentheses usage.

```Pharo
type=preferdepth: aNode	"Returns depth of a tree starting from the given node"			| leftDepth rightDepth |	l	eftDepth := -1.	aNode leftChild isNotNil 				ifTrue: [ leftDepth := self depth: aNode leftChild ].

	rightDepth := -1.	aNode rightChild isNotNil 				ifTrue: [ rightDepth := self depth: aNode rightChild ].

	^ leftDepth > rightDepth				ifTrue: [ 1 + leftDepth ]				ifFalse: [ 1 + rightDepth ]

over 

type=notdepth:aNode	"Returns depth of a tree starting from the given node"
	| leftDepth rightDepth |
	l	eftDepth := -1.	aNode leftChild isNotNil 
			ifTrue: [ leftDepth := self depth: (aNode leftChild) ].

	rightDepth := -1.	aNode rightChild isNotNil 
			ifTrue: [ rightDepth := self depth: (aNode rightChild) ].

		( leftDepth > rightDepth )				ifTrue: [ ^ (1 + leftDepth) ]				ifFalse: [^ (1 + rightDepth ) ].
```

--------------------------------

### Pharo Binary Message Execution Order

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Demonstrates Pharo's left-to-right execution of binary messages and how to use parentheses for mathematical correctness.

```Pharo
1 + 2 * 3 >>> 9
1 + (2 * 3) >>> 7
```

--------------------------------

### Preallocate Large Collections

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Advises preallocating collections when their size is known in advance to mitigate potential performance penalties during allocation. The example shows how to preallocate an `OrderedCollection` and compares its performance against a dynamically sized one.

```Smalltalk
| list |
list := OrderedCollection new: 10000.
1 to: 10000 do: [ :i |
	list add: i ]
```

```Smalltalk
| list |
list := OrderedCollection new: 100000.
1 to: 100000 do: [ :i |
	list add: i ]
```

```Smalltalk
[| list |
list := OrderedCollection new: 100000.
1 to: 100000 do: [ :i |
	list add: i ] ] bench "for 100,000 get 165.901 per second"
"for 10,000 get 5484.903 per second"
```

```Smalltalk
[| list |
list := OrderedCollection new.
1 to: 100000 do: [ :i |
	list add: i ] ] bench "for 100,000 get 79.368 per second"
"for 10,000 get 5278.544 per second"
```

--------------------------------

### MicAbstractBlock Initialize Method with LogStream

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This snippet shows the initialization of `MicAbstractBlock`, where the `logStream` is set to a new `WriteStream` on a `String`, providing a dedicated logging stream for each instance.

```Smalltalk
MicAbstractBlock >> initialize
    super initialize.
    children := OrderedCollection new.
    logStream := WriteStream on: (String new: 1000)
```

--------------------------------

### Follow conventions: Use 'at:' instead of 'get:' for dictionary-like access

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

When designing objects that mimic dictionary or set behavior, use idiomatic message names. For accessing properties like a style sheet, prefer 'at:' over 'get:'. Similarly, for collections, 'groupedBy:' is preferred over 'groupBy:'.

```Smalltalk
type=preferstylesheet
	at: #fontColor
```

```Smalltalk
type=notstylesheet
	get: #fontColor
```

```Smalltalk
type=preferaCollection
	groupedBy: [ :each | each odd ]
```

```Smalltalk
type=notaCollection
	groupBy: [ :each | each odd ]
```

```Smalltalk
type=preferseries
	at: #k3 put: 'x'.
```

```Smalltalk
type=notseries
	atKey: #k3 put: 'x'
```

```Smalltalk
type=preferaCollection
	at: #toto
```

```Smalltalk
aCollection atKey: #toto
```

--------------------------------

### Method Naming: Imperative Verbs for Actions

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Recommends using imperative verbs for messages that perform an action.

```Pharo
type=prefer
transform
selectors do: [:each |
	self pushDown: each].
selectors do: [:each |
	class removeMethod: each]
```

```Pharo
type=prefer
aReadStream peek
```

```Pharo
type=not
aReadStream word
```

```Pharo
type=prefer
aFace lookSurprised
aFace beSurprised
```

```Pharo
type=not
aFace surprised
```

```Pharo
type=prefer
skipSeparators
```

--------------------------------

### Active Voice and Short Sentences

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Use active voice and concise sentences for comments. Clearly state the method's action, arguments, effects, and output.

```Pharo Smalltalk
```"Active voice"createShell
	"Create the receiver's shell. Hook the focus callback."```
```

--------------------------------

### MicAbstractBlock Class Initialize Method

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

The `initialize` class method calls `reset` to ensure that the `DefaultStream` is properly initialized when the class is loaded or reset.

```Smalltalk
MicAbstractBlock class >> initialize
    self reset
```

--------------------------------

### Accessor Naming and Implementation (Pharo)

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Accessors (getters and setters) should be named consistently with the instance variable they refer to. Getters should match the variable name, and setters should append a colon. Avoid using `get` or `set` prefixes. Setters should only assign the value and return the receiver implicitly. Lazy initialization should be handled within the getter.

```Smalltalk
type=prefertiles	^ tiles
```

```Smalltalk
type=notgetTiles	^ tiles
```

```Smalltalk
type=notBinaryNode >> root: rootNode	    "Set a root node"	    ^ root := rootNode
```

```Smalltalk
type=notBinaryNode >> root: rootNode	    root := rootNode
```

```Smalltalk
type=prefertiles	^ tiles ifNil: [ tiles := OrderedCollection new ]
```

```Smalltalk
type=prefertiles:	aCollection	tiles := aCollection 
```

--------------------------------

### Method Selector Naming Convention

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Illustrates the correct convention for naming method selectors (methods) in Pharo, which should start with a lowercase letter and use descriptive names.

```Pharo
```type=preferGetMethodsNamesFromAClass: aClass
	"Example of a correctly named method selector"
	methodsNames := aClass selectors.
	methodsNames do: [ :each |
		names add: each ]```
over
```type=notGetMethodsNamesFromAClass: aClass
	"Example of a poorly named method selector"
	methodsNames := aClass selectors.
	methodsNames do: [ :each |
		names add: each ]```
```

--------------------------------

### Naming: Follow Domain Concepts and Culture

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Adhere to the project's domain concepts and established terminology. Avoid introducing new terms unless necessary and prioritize consistency over perceived precision.

```Pharo
prefer
	type=preferGnatXmlNode
over
	type=notnot GNAT_XML_Object

# Example: GNATInstaller should be GnatImporter, GNATImporter should be GnatASTLoader
```

--------------------------------

### MicAbstractBlock Initialize Method Using DefaultStream

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This refactored `initialize` method for `MicAbstractBlock` instances now assigns the class's `DefaultStream` to the instance's `logStream`, ensuring instances use the configured default.

```Smalltalk
MicAbstractBlock >> initialize
    super initialize.
    children := OrderedCollection new.
    logStream := DefaultStream
```

--------------------------------

### Object Naming: Common Nouns and Phrases

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Suggests using common nouns and phrases for non-Boolean objects.

```Pharo
type=prefer
"In class Vehicle..."
numberOfTires
numberOfDoors
"In class AlarmClock..."
time
alarmTime
"In class TypeSetter..."
page
font
outputDevice
```

```Pharo
type=prefer
tireCount
```

--------------------------------

### Method Naming: Indicate Flow with Prepositions

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Emphasizes using meaningful names with prepositions to indicate the direction of a process state change.

```Pharo
type=not
Configuration flattenProperties: aDictionary
```

```Pharo
type=prefer
Configuration flattenPropertiesFrom: aDictionary
Configuration flattenPropertiesInto: aDictionary
```

```Pharo
type=prefer
changeField: anInteger to: anObject
```

```Pharo
type=prefer
ReadWriteStream on: aCollection.
```

```Pharo
type=not
ReadWriteStream for: aCollection.
```

```Pharo
type=prefer
File openOn: stream
```

```Pharo
type=not
File with: stream
```

```Pharo
type=prefer
display: anObject on: aMedium
```

```Pharo
type=not
display: anObject using: aMedium
```

--------------------------------

### Parameter Naming Conventions (Pharo)

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Avoid including the parameter's type in the method name if the parameter itself is clearly named. This prevents redundancy and keeps method names concise. For example, `at: aKey put: aFile` is preferred over `atKey: aKey putFile: aFile`.

```Smalltalk
type=preferfileSystem at: aKey put: aFile
```

```Smalltalk
type=notfileSystem atKey: aKey putFiIe: aFile
```

```Smalltalk
"for semantic-based parameter names"
fileSystem atKey: index putFile: pathName
```

```Smalltalk
"useful when your class has several #at:put: methods"
fileSystem definitionAt: aKey put: definition
```

```Smalltalk
type=preferaFace changeTo: expression
```

```Smalltalk
type=notaFace changeExpressionTo: expression
```

--------------------------------

### Avoiding Singletons in Pharo

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Explains why singletons are discouraged in Pharo, likening them to disguised global variables that hinder modularity and testing. Suggests alternatives like adding instance variables.

--------------------------------

### Pharo Method Length Guideline

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Highlights the guideline in Pharo to write small methods, with a median of 3 lines of code. Small methods are easier to read, test, reuse, and customize.

--------------------------------

### MicAbstractBlock closeMe Method (Original)

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This snippet shows the original implementation of the `closeMe` method in `MicAbstractBlock` which directly writes to `Transcript`, a global singleton. This approach hinders modularity and testability.

```Smalltalk
MicAbstractBlock >> closeMe
    Transcript << 'Closing ' << self class name; cr; endEntry
```

--------------------------------

### Self-Documenting Code Principle

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Prioritize writing self-documenting code. Comments should highlight important aspects or explain complex algorithms, not rephrase obvious code.

```Pharo Smalltalk
```type=prefer| result |
result := self employees
 collect: [:employee | employee salary > amount].```
```

--------------------------------

### Styling Examples in Markdown

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/index.md

Demonstrates various ways to apply styles within markdown content, potentially for headings, lists, emphasis, and custom elements. This section likely covers basic markdown syntax and any custom extensions used in the project.

```markdown
# Main Title

This is a paragraph with **bold** and *italic* text.

## Section Heading

- List item 1
- List item 2

```
// Example of a code block
const greeting = "Hello, World!";
console.log(greeting);
```

[Link to another section](another-section.md)
```

--------------------------------

### highlight.js API Documentation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/CHANGES.md

Provides documentation for the highlight.js API, covering its usage with Node.js and browser environments. It details how to install the library via npm and where to find comprehensive API documentation.

```APIDOC
highlight.js API Documentation:

Installation with npm:
  npm install highlight.js

Usage:
  - Browser environment
  - Node.js environment

API Documentation Location:
  http://softwaremaniacs.org/wiki/doku.php/highlight.js:api
```

--------------------------------

### Pharo Binary Message in Keyword Expressions

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Shows that binary messages are executed before keyword messages, making parentheses around them redundant.

```Pharo
type=preferreducedX do: [ :row | 			(row at: 'target') = 'Iris-setosa' 				ifTrue: [ a add: row asArray ] ].
type=notreducedX do: [ :row | 			( (row at: 'target') = 'Iris-setosa') 				ifTrue: [ a add: (row asArray) ] ].
```

--------------------------------

### Method Naming: Prefix 'as' for Conversion

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

States the convention of prefixing the target class name with `as` when converting an object to another type.

```Pharo
anArray asOrderedCollection
```

--------------------------------

### MicAbstractBlock closeMe Method (Refactored)

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

The refactored `closeMe` method now writes to the instance's `logStream` instead of the global `Transcript`, improving encapsulation and control over logging.

```Smalltalk
MicAbstractBlock >> closeMe
    logStream << 'Closing ' << self class name; cr
```

--------------------------------

### printString vs. asString in Pharo

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Demonstrates the difference between `printString` and `asString` for symbols and strings in Pharo. `printString` is for debugging and includes quotes for strings, while `asString` converts to a string representation.

```Pharo
#foo printString >>> '#foo'
#foo asString >>> 'foo'
'foo' asString >>> 'foo'
'foo' printString >>> '''foo'''
```

--------------------------------

### Naming: Limit or Use Abbreviations Consistently

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Abbreviations can be obscure to newcomers. If used, ensure they are applied consistently throughout the project. Prefer full names or well-understood acronyms.

```Pharo
prefer
	type=preferASTNode
over
	type=preferTreeNodeAbstractSyntaxTreeNode
```

--------------------------------

### Proper Transcript Usage in Pharo

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Advises against hardcoding `Transcript` references for logging in Pharo. Recommends using helper methods like `traceCr:` to allow for easier redirection of logging output.

```Pharo
myMethod    Transcript show: 'foo' ; cr
myMethod   self traceCr: 'foo'
```

--------------------------------

### Efficient `printString` Implementation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Demonstrates how `printString` is implemented in Pharo, involving streams and limits. It highlights a common pitfall where `printString` is called within `printOn:`, leading to nested stream creation. The preferred approach is to use `print:` on the stream directly.

```Smalltalk
Object >> printString
	"Answer a String whose characters are a description of the receiver. 
	If you want to print without a character limit, use fullPrintString."
	^ self printStringLimitedTo: 50000

Object >> printStringLimitedTo: limit
	"Answer a String whose characters are a description of the receiver.
	If you want to print without a character limit, use fullPrintString."
	^self printStringLimitedTo: limit using: [:s | self printOn: s]

Object >> printStringLimitedTo: limit using: printBlock
	"Answer a String whose characters are a description of the receiver
	produced by given printBlock. It ensures the result will be not bigger than given limit"
	| limitedString |
	limitedString := String streamContents: printBlock limitedTo: limit.
	limitedString size < limit ifTrue: [^ limitedString].
	^ limitedString , '...etc...'


```

```Smalltalk
type=not
MessageTally >> displayStringOn: aStream
	self displayIdentifierOn: aStream.
	aStream 
		nextPutAll: ' (';
		nextPutAll: self tally printString;
		nextPutAll: ')'

```

```Smalltalk
type=prefer
MessageTally >> displayStringOn: aStream
	self displayIdentifierOn: aStream.
	aStream 
		nextPutAll: ' (';
		print: self tally;
		nextPutAll: ')'

```

```Smalltalk
Stream >> print: anObject
	"Have anObject print itself on the receiver."
	anObject printOn: self
```

--------------------------------

### Idiomatic 'initialize' Method Structure

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Illustrates the conventional way to structure the `initialize` method in Pharo. The `initialize` method should primarily modify the receiver and not return a value. It's recommended to call `super initialize` first, followed by instance-specific initializations, although the order can be adjusted if necessary.

```Pharo
not initialize
	default := 'no'.
	^ super initialize

prefer initialize
	default := 'no'.
	super initialize

prefer initialize
	super initialize
	default := 'no'.
```

--------------------------------

### Use streamContents for Stream Manipulation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Recommends using the `streamContents:` message with a block for manipulating potentially long streams. This approach simplifies stream creation and access by providing a ready-to-use stream directly within the block.

```Smalltalk
type=preferString streamContents: [:s | self displayStringOn: s]
```

```Smalltalk
type=notstream := WriteStream on: (String new: 1000).
stream ...
^ stream contents
```

--------------------------------

### Method Body Indentation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Illustrates the importance of proper indentation for method bodies to convey structure and improve readability. Contrasts poorly indented code with the preferred, indented style.

```Smalltalk
type=notinitializesuper initialize.
symbols := Bag new.
names := Set new
```

```Smalltalk
type=preferinitialize
	super initialize.
	symbols := Bag new.
	names := Set new
```

--------------------------------

### Interrogative Form for Testing Methods (Pharo)

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

When checking the state of an object, use method names that start with interrogative verbs like `is`, `has`, or `does`. This clearly communicates the method's purpose as a test or query. For example, `isAtLineEnd` is preferred over `atLineEnd` for a boolean check.

```Smalltalk
type=preferisAtLineEnd
```

```Smalltalk
type=notatLineEnd
```

```Smalltalk
type=preferaVehicle hasFourWheels
```

```Smalltalk
type=notaVehicle fourWheels
```

--------------------------------

### Class Naming: Avoid Exposing Implementation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Class names should not reveal the internal implementation details, as these may change over time. Focus on the 'what' rather than the 'how'.

```Pharo
prefer
	type=preferPropertyNameContactBook
over
	type=notPropertyNameStringContactDictionary
```

--------------------------------

### Naming: Avoid Numbers

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Refrain from using numbers to differentiate similar identifiers. Numbers do not aid in understanding the difference between versions or implementations. If multiple versions are necessary, clearly document the reason.

```Pharo
prefer
	type=preferStackBasedInlineParserNewInlineParserCleanerInlineParser
over
	type=notInlineParser2
```

--------------------------------

### Method Naming: Interrogative vs. Imperative

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Highlights the importance of using appropriate forms for interrogative (e.g., `isOptimized`) and imperative (e.g., `beOptimized`, `triggerOptimization`) meanings.

```Pharo
optimized
```

```Pharo
triggerOptimization
```

--------------------------------

### Class Naming: Natural Language and Abbreviations

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Favor natural language in class names, avoiding obscure abbreviations or shortened terms. Use abbreviations consistently if they are common and well-understood within the project context.

```Pharo
prefer
	type=preferRandomNumberGenerator
over
	type=notRandNumbGen

prefer
	type=preferCSVImporter
over
	type=notCSVImport

prefer
	type=preferRemoteControl
over
	type=notRemControl

prefer
	type=preferPlayer
over
	type=notBoardMan
```

--------------------------------

### MicAbstractBlock Class Definition with LogStream

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

This code defines the `MicAbstractBlock` class, adding an instance variable `logStream` to manage logging output, thereby decoupling it from global variables.

```Smalltalk
Object subclass: #MicAbstractBlock
    instanceVariableNames: 'parent children parser logStream'
    classVariableNames: ''
    package: 'Microdown-Model'
```

--------------------------------

### Basic Highlight.js Initialization

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.md

Demonstrates the minimal HTML and JavaScript required to initialize Highlight.js on a webpage. It includes linking the CSS, the JavaScript library, and calling `initHighlightingOnLoad` for automatic language detection.

```html
<link rel="stylesheet" href="/path/to/styles/default.css">
<script src="/path/to/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
```

--------------------------------

### Variable and Class Naming Conventions

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Class names, global variables, pool variables, and class variables should start with an uppercase letter, followed by camel case for compound words. Instance variables, temporary variables, method parameters, and selectors should start with a lowercase letter, also using camel case for compound words.

```Pharo
Class Names, Global Variables, Pool Variables, Class Variables:
Point "Class"
Transcript "global variable"
PackageGlobalOrganizer "class variables"

Instance Variables, Temporary Variables, Method Parameters, Selectors:
prefer
	type=prefer| dataset f xMatrix scale x |
over
	type=not| dataset f Xmatrix scale X |

prefer
	type=prefermaxLimit
instead of
	type=notmaxlimitMAXLIMIT
```

--------------------------------

### Highlight.js API Documentation

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.ru.md

Provides an overview of key Highlight.js API functions for initialization and configuration.

```APIDOC
initHighlightingOnLoad()
  - Initializes syntax highlighting for all code blocks on the page when the DOM is loaded.

highlightBlock(block, canIgnoreIllegals)
  - Highlights a single code block element.
  - Parameters:
    - block: The DOM element containing the code.
    - canIgnoreIllegals: Boolean, whether to ignore illegal syntax (optional).

configure(options)
  - Configures Highlight.js with various options.
  - Parameters:
    - options: An object containing configuration settings.
      - useBR: Boolean, use '<br>' tags for line breaks (default: false).
      - classPrefix: String, prefix for CSS classes (default: 'hljs').
      - tabReplace: String, string to replace tabs with (e.g., '    ').
      - languages: Array of language names to load.
```

--------------------------------

### `printString` vs. `displayString`

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Explains the difference between `printString` and `displayString` in Pharo. `printString` is primarily for debugging and often includes class information, while `displayString` is for user-facing display, typically showing a more refined representation of the object.

```Smalltalk
aPerson printString >>> 'aPerson ("John Doe")'
aPerson displayString >>> 'John Doe'
```

--------------------------------

### Use Descriptive Names to Avoid Cryptic Ones

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/Chapters/withStyle.md

Choose names that clearly and unambiguously capture the domain entities they represent. Do not shy away from using more characters to make the meaning explicit. Leverage code completion tools if typing is a concern.

```Pharo
Prefer ```type=preferdayOfWeek``` over ```type=notNot dow```
Prefer ```type=preferseconds``` over ```type=notNot sec```
Prefer ```type=prefercopyMenu``` over ```type=notNot cMenu```
```

--------------------------------

### Highlighting in a Web Worker

Source: https://github.com/squarebracketassociates/booklet-pharowithstyle/blob/master/_support/html/highlightjs/README.md

Provides code examples for running Highlight.js within a web worker to prevent browser freezing with large code blocks. It includes the main script logic for communication and the worker script for processing.

```javascript
addEventListener('load', function() {
  var code = document.querySelector('#code');
  var worker = new Worker('worker.js');
  worker.onmessage = function(event) { code.innerHTML = event.data; }
  worker.postMessage(code.textContent);
})
```

```javascript
onmessage = function(event) {
  importScripts('<path>/highlight.pack.js');
  var result = self.hljs.highlightAuto(event.data);
  postMessage(result.value);
}
```
Tokens:
Raw