Download Full ebookname - Read Now at ebookname.

com

Software Design by Example 1st Edition Greg Wilson

https://ebookname.com/product/software-design-by-
example-1st-edition-greg-wilson/

OR CLICK BUTTON

DOWLOAD EBOOK

Discover More Ebook - Explore Now at ebookname.com

Instant digital products (PDF, ePub, MOBI) available
Download now and explore formats that suit you...

SuperSpeed Device Design By Example 1rd; Edition John Hyde

https://ebookname.com/product/superspeed-device-design-by-example-1rd-
edition-john-hyde/

ebookname.com

Swift by Example 1st Edition Scalzo

https://ebookname.com/product/swift-by-example-1st-edition-scalzo/

ebookname.com

Capell s Shakespeariana Catalogue of the Books Presented

by Edward Capell to the Library of Trinity College in
Cambridge compiled by W W Greg 1st Edition Walter Wilson
Greg
https://ebookname.com/product/capell-s-shakespeariana-catalogue-of-
the-books-presented-by-edward-capell-to-the-library-of-trinity-
college-in-cambridge-compiled-by-w-w-greg-1st-edition-walter-wilson-
greg/
ebookname.com

Structural and Evolutionary Genomics Natural Selection in

Genome Evolution 1st Edition Giorgio Bernardi (Eds.)

https://ebookname.com/product/structural-and-evolutionary-genomics-
natural-selection-in-genome-evolution-1st-edition-giorgio-bernardi-
eds/
ebookname.com
Script Culture and the American Screenplay 1st Edition
Kevin Alexander Boon

https://ebookname.com/product/script-culture-and-the-american-
screenplay-1st-edition-kevin-alexander-boon/

ebookname.com

Allied Axis The Photo Journal of the Second World War

Issue 3 1st Edition Patrick Stansell

https://ebookname.com/product/allied-axis-the-photo-journal-of-the-
second-world-war-issue-3-1st-edition-patrick-stansell/

ebookname.com

Does Inflation in China Affect the United States and Japan

1st Edition Luke Willard

https://ebookname.com/product/does-inflation-in-china-affect-the-
united-states-and-japan-1st-edition-luke-willard/

ebookname.com

Flight from Wonder An Investigation of Scientific

Creativity 1st Edition Albert Rothenberg

https://ebookname.com/product/flight-from-wonder-an-investigation-of-
scientific-creativity-1st-edition-albert-rothenberg/

ebookname.com

Processing of High Temperature Superconductors Proceedings

of the symposium held at the 104th Annual Meeting of The
American Ceramic Society April 28 May 1 Transactions
Ceramic Transactions Series 1st Edition Amit Goyal
https://ebookname.com/product/processing-of-high-temperature-
superconductors-proceedings-of-the-symposium-held-at-the-104th-annual-
meeting-of-the-american-ceramic-society-april-28-may-1-transactions-
ceramic-transactions-series-1st/
ebookname.com
A New Humanism 1st Edition Daisaku Ikeda

https://ebookname.com/product/a-new-humanism-1st-edition-daisaku-
ikeda/

ebookname.com
 Software Design by
Example

The best way to learn design in any field is to study examples, and some of the best examples
of software design come from the tools programmers use in their own work. Software De-
sign by Example: A Tool-Based Introduction with Python therefore builds small versions
of the things programmers use in order to demystify them and give some insights into how ex-
perienced programmers think. From a file backup system and a testing framework to a regular
expression matcher, a browser layout engine, and a very small compiler, we explore common
design patterns, show how making code easier to test also makes it easier to re-use, and help
readers understand how debuggers, profilers, package managers, and version control systems
work so that they can use them more effectively.

This material can be used for self-paced study, in an undergraduate course on software design,
or as the core of an intensive weeklong workshop for working programmers. Each chapter has
a set of exercises ranging in size and difficulty from half a dozen lines to a full day’s work. Read-
ers should be familiar with the basics of modern Python, but the more advanced features of the
language are explained and illustrated as they are introduced.

All the written material in this project can be freely re-used under the terms of the Creative
Commons - Attribution license, while all of the software is made available under the terms of
the Hippocratic License. All proceeds from the sale of this book will go to support the Red Door
Family Shelter in Toronto.

Features:
•  Teaches software design by showing programmers how to build the tools they use every day
•  Each chapter includes exercises to help readers check and deepen their understanding
•  All the example code can be downloaded, re-used, and modified under an open license
Dr. Greg Wilson is a programmer, author, and educator based in Toronto. He co-founded and
was the first Executive Director of Software Carpentry, which has taught basic software skills to
tens of thousands of researchers worldwide, and he has authored or edited over a dozen books
(including two for children). Greg is a member of the Python Software Foundation and a recipi-
ent of ACM SIGSOFT’s Influential Educator of the Year Award.
Taylor & Francis
Taylor & Francis Group
http://taylorandfrancis.com
 Software Design by
Example
A Tool-Based Introduction with Python

Greg Wilson
First edition published 2024
by CRC Press
2385 NW Executive Center Drive, Suite 320, Boca Raton FL 33431

and by CRC Press

4 Park Square, Milton Park, Abingdon, Oxon, OX14 4RN

CRC Press is an imprint of Taylor & Francis Group, LLC

© 2024 Greg Wilson

Reasonable efforts have been made to publish reliable data and information, but the author and publisher cannot as-
sume responsibility for the validity of all materials or the consequences of their use. The authors and publishers have
attempted to trace the copyright holders of all material reproduced in this publication and apologize to copyright holders
if permission to publish in this form has not been obtained. If any copyright material has not been acknowledged please
write and let us know so we may rectify in any future reprint.

Except as permitted under U.S. Copyright Law, no part of this book may be reprinted, reproduced, transmitted, or
utilized in any form by any electronic, mechanical, or other means, now known or hereafter invented, including pho-
tocopying, microfilming, and recording, or in any information storage or retrieval system, without written permission
from the publishers.

For permission to photocopy or use material electronically from this work, access www.copyright.com or contact the
Copyright Clearance Center, Inc. (CCC), 222 Rosewood Drive, Danvers, MA 01923, 978-750-8400. For works that are
not available on CCC please contact mpkbookspermissions@tandf.co.uk

Trademark notice: Product or corporate names may be trademarks or registered trademarks and are used only for iden-
tification and explanation without intent to infringe.

ISBN: 978-1-032-72525-3 (hbk)

ISBN: 978-1-032-72521-5 (pbk)
ISBN: 978-1-032-72523-9 (ebk)

DOI: 10.1201/9781032725239

Typeset in Arial
by KnowledgeWorks Global Ltd.

Publisher’s note: This book has been prepared from camera-ready copy provided by the authors.
 Dedication

This one’s for Mike and Jon:

I’m glad you always found time to chat.
Taylor & Francis
Taylor & Francis Group
http://taylorandfrancis.com
Contents

1 Introduction 1
1.1 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 The Big Ideas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.5 What People Are Saying . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.7 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Objects and Classes 7

2.1 Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.4 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3 Finding Duplicate Files 17

3.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Hashing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3 Better Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4 Matching Patterns 25
4.1 Simple Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.2 Rethinking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.4 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

5 Parsing Text 35
5.1 Tokenizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.2 Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.4 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

6 Running Tests 43
6.1 Storing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.2 Finding Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.3 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.4 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

vii
viii Contents

7 An Interpreter 51
7.1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.2 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.3 Introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

8 Functions and Closures 59

8.1 Definition and Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
8.2 Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
8.3 Closures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
8.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

9 Protocols 69
9.1 Mock Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.2 Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.3 Decorators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.4 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
9.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

10 A File Archiver 81
10.1 Saving Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
10.2 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
10.3 Tracking Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.4 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
10.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
10.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

11 An HTML Validator 91
11.1 HTML and the DOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
11.2 The Visitor Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
11.3 Checking Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
11.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
11.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

12 A Template Expander 99
12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
12.2 Managing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
12.3 Visiting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
12.4 Implementing Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.5 Control Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
12.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
12.7 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

13 A Code Linter 111

13.1 Machinery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
13.2 Finding Duplicate Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
13.3 Finding Unused Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
13.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
13.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Contents ix

14 Page Layout 119

14.1 Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
14.2 Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
14.3 Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
14.4 Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
14.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
14.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

15 Performance Profiling 131

15.1 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
15.2 Row-Wise Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
15.3 Column-Wise Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
15.4 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
15.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
15.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

16 Object Persistence 145

16.1 Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
16.2 Converting to Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
16.3 Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
16.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
16.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

17 Binary Data 155

17.1 Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
17.2 Bitwise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
17.3 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
17.4 And Now, Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
17.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
17.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

18 A Database 165
18.1 Starting Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
18.2 Saving Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
18.3 A File-Backed Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
18.4 Playing with Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
18.5 Persisting Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
18.6 Cleaning Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
18.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
18.8 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

19 A Build Manager 177

19.1 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
19.2 Initial Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
19.3 Topological Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
19.4 A Better Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
19.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
19.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
x Contents

20 A Package Manager 187

20.1 Semantic Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
20.2 Exhaustive Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
20.3 Generating Possibilities Manually . . . . . . . . . . . . . . . . . . . . . . . 191
20.4 Incremental Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
20.5 Using a Theorem Prover . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
20.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
20.7 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

21 Transferring Files 201

21.1 Using TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
21.2 Chunking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
21.3 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
21.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
21.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

22 Serving Web Pages 209

22.1 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
22.2 Hello, Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
22.3 Serving Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
22.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
22.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
22.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

23 A File Viewer 219

23.1 Curses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
23.2 Windowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
23.3 Moving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
23.4 Refactoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
23.5 Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
23.6 Viewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
23.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
23.8 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

24 Undo and Redo 233

24.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
24.2 Insertion and Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
24.3 Going Backward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
24.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
24.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

25 A Virtual Machine 243

25.1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
25.2 Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
25.3 Assembly Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
25.4 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
25.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
25.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Contents xi

26 A Debugger 255
26.1 One Step at a Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
26.2 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
26.3 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
26.4 Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
26.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
26.6 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

27 Conclusion 267

A Bibliography 269

B Bonus Material 271

B.1 Using Function Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
B.2 Lazy Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
B.3 Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
B.4 Tracing Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
B.5 Inspecting Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
B.6 User-Defined Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
B.7 Floating Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
B.8 Big and Little Endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
B.9 Generating Test Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

C Syllabus 287

D License 293
D.1 Writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
D.2 Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

E Code of Conduct 297

E.1 Our Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
E.2 Our Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
E.3 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
E.4 Enforcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
E.5 Attribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

F Contributing 299
F.1 Editing Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
F.2 Making Decisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
F.3 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

G Glossary 303

Index 327
Taylor & Francis
Taylor & Francis Group
http://taylorandfrancis.com
1
Introduction

• The complexity of a system increases more rapidly than its size.

• The best way to learn design is to study examples, and the best programs to use as
examples are the ones programmers use every day.

• These lessons assume readers can write small programs and want to write larger
ones, or are looking for material to use in software design classes that they teach.

• All of the content is free to read and re-use under open licenses, and all royalties
from sales of this book will go to charity.

Terms defined: cognitive load

The best way to learn design in any field is to study examples [Schon1984; Petre2016],
and the most approachable examples are ones that readers are already familiar with. These
lessons therefore build small versions of tools that programmers use every day1 to show
how experienced software designers think. Along the way, they introduce some fundamen-
tal ideas in computer science that many self-taught programmers haven’t encountered. We
hope these lessons will help you design better software yourself, and that if you know how
programming tools work, you’ll be more likely to use them and better able to use them well.

1.1 Audience
This learner persona [Wilson2019] describes who this book is for:

Maya has a master’s degree in genomics. She knows enough Python to analyze
data from her experiments, but struggles to write code other people can use. These
lessons will show her how to design, build, and test large programs in less time and
with less pain.

Like Maya, you should be able to:

• Write Python programs using lists, loops, conditionals, dictionaries, and functions.

• Puzzle your way through Python programs that use classes and exceptions.

• Run basic Unix shell commands like ls and mkdir.

• Read and write a little bit of HTML.

• Use Git2 to save and share files. (It’s OK not to know the more obscure commands3 .)
1 https://en.wikipedia.org/wiki/Programming_tool
2 https://git-scm.com/
3 https://git-man-page-generator.lokaltog.net/

1
2 1 Introduction

2
19 A Build Objects and Running Page 14
Manager Classes Tests Layout

23 24 16 6 12
A File Undo and Object 7 An A Template
Viewer Redo Persistence Interpreter Expander

17 8 11
A Virtual Binary Functions and An HTML
A Debugger
Machine Data Closures Validator
26 25
18 9 12
A Code 5 Parsing
A Database Protocols
Linter Text

Legend
15 10 3
4
Performance A File Finding
source
Profiling Archiver Duplicate Files Matching
Patterns
sink 21
22 Serving Transferring A Package 20
Web Pages Files Manager

Figure 1.1: Lesson topics and dependencies.

These chapters (Figure 1.1) are also designed to help another persona:

Yim teaches two college courses on software development. They are frustrated that
so many books talk about details but not about design and use examples that their
students can’t relate to. This book will give them material they can use in class and
starting points for course projects.

1.2 The Big Ideas

Our approach to design is based on three big ideas. First, as the number of components
in a system grows, the complexity of the system increases rapidly (Figure 1.2). However,
the number of things we can hold in working memory at any time is fixed and fairly small
[Hermans2021]. If we want to build large programs that we can understand, we therefore
need to construct them out of pieces that interact in a small number of ways. Figuring out
what those pieces and interactions should be is the core of what we call “design”.
Second, “making sense” depends on who we are. When we use a low-level language,
we incur the cognitive load of assembling micro-steps into something more meaningful.
When we use a high-level language, on the other hand, we incur a similar load translating
functions of functions into actual operations on actual data.
More experienced programmers are more capable at both ends of the curve, but that’s
not the only thing that changes. If a novice’s comprehension curve looks like the lower one
in Figure 1.3, then an expert’s looks like the upper one. Experts don’t just understand
√ more
at all levels of abstraction; their preferred level has also shifted so they find x2 + y 2 easier
to read than the Medieval equivalent “the side of the square whose area is the sum of the
areas of the two squares whose sides are given by the first part and the second part”. This
1.3 Formatting 3

A B A B

A B
C F C F

C
D E D E

3 components have 6 components have 2 components with 3 sub-components

3 interactions 30 interactions have 7 interactions

Figure 1.2: How complexity grows with size.

expert

novice
Comprehension

Abstraction

Figure 1.3: Novice and expert comprehension curves.

curve means that for any given task, the code that is quickest for a novice to comprehend
will almost certainly be different from the code that an expert can understand most quickly.
Our third big idea is that programs are just another kind of data. Source code is just text,
which we can process like other text files. Likewise, a program in memory is just a data
structure that we can inspect and modify like any other. Treating code like data enables us
to solve hard problems in elegant ways, but at the cost of increasing the level of abstraction
in our programs. Once again, finding the balance is what we mean by “design”.

1.3 Formatting
We display Python source code like this:
for ch in "example ":
print(ch)

and Unix shell commands like this:

for filename in *.dat
do
cut -d , -f 10 $filename
done
4 1 Introduction

Data files and program output are shown like this:

- name: read
params:
- sample_data.csv

alpha
beta
gamma
delta

We use ... to show where lines have been omitted, and occasionally break lines in
unnatural ways to make them fit on the page. Where we do this, we end all but the last line
with a single backslash \. Finally, we show glossary entries in bold text and write functions
as function_name rather than function_name(). The latter is more common, but the empty
parentheses makes it hard to tell whether we’re talking about the function itself or a call to
the function with no parameters.

1.4 Usage
The source for this book is available in our Git repository4 and all of it can be read on our
website5 . All of the written material in this book is licensed under the Creative Commons -
Attribution - NonCommercial 4.0 International license6 (CC-BY-NC-4.0), while the software
is covered by the Hippocratic License7 . The first license allows you to use and remix this
material for noncommercial purposes, as-is or in adapted form, provided you cite its orig-
inal source; if you want to sell copies or make money from this material in any other way,
you must contact us8 and obtain permission first. The second license allows you to use
and remix the software on this site provided you do not violate international agreements
governing human rights; please see Appendix D for details.
If you would like to improve what we have, add new material, or ask questions, please
file an issue in our GitHub repository9 or send an email10 . All contributors are required to
abide by our Code of Conduct (Appendix E).

1.5 What People Are Saying

Here’s what people said about the JavaScript version of this book [Wilson2022a]:
• Jessica Kerr11 : “Software Design by Example is the book I’ll recommend to every new
dev... It is nice to you. It wants you to succeed... It’s a bridge from ‘learn to program’ to
working programmer.”
4 https://github.com/gvwilson/sdxpy/
5 https://third-bit.com/sdxpy/
6 https://creativecommons.org/licenses/by-nc/4.0/
7 https://firstdonoharm.dev/
8 mailto:gvwilson@third-bit.com
9 https://github.com/gvwilson/sdxpy/
10 mailto:gvwilson@third-bit.com
11 https://jessitron.com/2023/02/20/book-review-software-design-by-example/
1.6 Acknowledgments 5

• Jenn Schiffer12 : “I am v much enjoying gvwilson’s book Software Design by Example. It

makes me miss teaching, it would be such a fun text to use!”
• Emily Gorcenski13 : “There’s a lot of books on programming but fewer books that couple
software development with effective and practical use of tools, presenting a language not
as a main course but as a part of an engineering ecosystem. Greg Wilson’s book hits all
the right notes in bringing together theory, pragmatism, and best practices.”
• Danielle Navarro14 : “The book is really bloody lovely.”

1.6 Acknowledgments
Like [Wilson2022a], this book was inspired by [Kamin1990; Kernighan1979; Kernighan1981;
Kernighan1983; Kernighan1988; Oram2007; Wirth1976] and by:
• The Architecture of Open Source Applications 15 series [Brown2011; Brown2012; Arm-
strong2013; Brown2016];
• Mary Rose Cook’s16 Gitlet17 ;
• Matt Brubeck’s18 browser engine tutorial19 ;
• Web Browser Engineering 20 by Pavel Panchekha21 and Chris Harrelson22 ;
• Connor Stack’s23 database tutorial24 ;
• Maël Nison’s25 package manager tutorial26 ;
• Paige Ruten’s27 kilo text editor28 and Wasim Lorgat’s29 editor tutorial30 ;
• Bob Nystrom’s31 Crafting Interpreters 32 [Nystrom2021]; and
• the posts and zines33 created by Julia Evans34 .
12 https://mastodon.social/@jenn@pixel.kitchen/109985276835264400
13 https://emilygorcenski.com/post/book-report-software-design-by-example-by-greg-wilson/
14 https://blog.djnavarro.net/posts/2023-05-31_software-design-by-example/
15 https://aosabook.org/
16 https://maryrosecook.com/
17 http://gitlet.maryrosecook.com/
18 https://limpet.net/mbrubeck/
19 https://limpet.net/mbrubeck/2014/08/08/toy-layout-engine-1.html
20 https://browser.engineering/
21 https://pavpanchekha.com/
22 https://twitter.com/chrishtr
23 https://connorstack.com/
24 https://cstack.github.io/db_tutorial/
25 https://arcanis.github.io/
26 https://classic.yarnpkg.com/blog/2017/07/11/lets-dev-a-package-manager/
27 https://viewsourcecode.org/
28 https://viewsourcecode.org/snaptoken/kilo/index.html
29 https://wasimlorgat.com/
30 https://github.com/seem/editor
31 http://journal.stuffwithstuff.com/
32 https://craftinginterpreters.com/
33 https://wizardzines.com/
34 https://jvns.ca/
6 1 Introduction

I am grateful to Miras Adilov, Alvee Akand, Rohan Alexander, Alexey Alexapolsky, Lina
Andrén, Alberto Bacchelli, Yanina Bellini Saibene, Matthew Bluteau, Adrienne Canino, Marc
Chéhab, Stephen Childs, Hector Correa, Socorro Dominguez, Christian Drumm, Christian
Epple, Julia Evans, Davide Fucci, Thomas Fritz, Francisco Gabriel, Florian Gaudin-Delrieu,
Craig Gross, Jonathan Guyer, McKenzie Hagen, Han Qi, Fraser Hay, Alexandru Hurjui,
Bahman Karimi, Carolyn Kim, Kitsios Konstantinos, Jenna Landy, Peter Lin, Zihan Liu,
Becca Love, Dan McCloy, Ramiro Mejia, Michael Miller, Firas Moosvi, Joe Nash, Sheena
Ng, Reiko Okamoto, Juanan Pereira, Mahmoodur Rahman, Arpan Sarkar, Silvan Schlegel,
Rosan Shanmuganathan, Dave W. Smith, Stephen M. Sturdevant, Diyar Taskiran, Ece Tur-
nator, and Yao Yundong for feedback on early drafts of this material.
I am also grateful to Shashi Kumar for help with LaTeX, to Odin Beuchat35 for help with
JavaScript, and to the creators of Black36 , flake837 , Glosario38 , GNU Make39 , isort40 , ark41 ,
LaTeX42 , pip43 , Python44 , Remark45 , WAVE46 , and many other open source tools: if we all
give a little, we all get a lot.
All royalties from this book will go to the Red Door Family Shelter47 in Toronto.

1.7 Exercises
Setting Up
1. Use pip48 to install Black49 , flake850 , and isort51 on your computer.

2. Run them on a few programs you have already written. (The file setup.cfg in the root
directory of this book’s GitHub repository52 has the settings we use for these tools.) What
problems do they report? Which of these reports do you disagree with?

Avoiding Potholes
Go to the GitHub repository53 for this book and look at the open issues. Which of them can
you understand? What makes the others hard to understand? What could you add, leave
out, or write differently when you report a problem that you have found?

35 https://www.drafolin.ch/
36 https://black.readthedocs.io/
37 https://flake8.pycqa.org/
38 https://glosario.carpentries.org/
39 https://www.gnu.org/software/make/
40 https://pycqa.github.io/isort/
41 https://www.dmulholl.com/docs/ark/main/
42 https://www.latex-project.org/
43 https://pip.pypa.io/
44 https://www.python.org/
45 https://remarkjs.com/
46 https://wave.webaim.org/
47 https://www.reddoorshelter.ca/
48 https://pip.pypa.io/
49 https://black.readthedocs.io/
50 https://flake8.pycqa.org/
51 https://pycqa.github.io/isort/
52 https://github.com/gvwilson/sdxpy/
53 https://github.com/gvwilson/sdxpy/
2
Objects and Classes

• Objects are useful without classes, but classes make them easier to understand.

• A well-designed class defines a contract that code using its instances can rely on.

• Objects that respect the same contract are polymorphic, i.e., they can be used
interchangeably even if they do different specific things.

• Objects and classes can be thought of as dictionaries with stereotyped behavior.

• Most languages allow functions and methods to take a variable number of

arguments.

• Inheritance can be implemented in several ways that differ in the order in which
objects and classes are searched for methods.

Terms defined: alias, argument, cache, class method, constructor, derived class,
design by contract, monkey patching, multiple inheritance, object-oriented
programming, parameter, polymorphism, recursion, spread, static method,
upcall, varargs

We are going to create a lot of objects and classes in these lessons, and they will be a
lot easier to use if we understand how they are implemented. Historically, object-oriented
programming (OOP) was invented to solve two problems:

1. What is a natural way to represent real-world “things” in code?

2. How can we organize code to make it easier to understand, test, and extend?

2.1 Objects
As a motivating problem, let’s define some of the things a generic shape in a drawing
package must be able to do:
class Shape:
def __init__(self , name ):
self.name = name

def perimeter(self ):
raise NotImplementedError (" perimeter ")

def area(self ):
raise NotImplementedError (" area ")

A specification like this is sometimes called a contract because an object must satisfy it
in order to be considered a shape, i.e., must provide methods with these names that do

7
8 2 Objects and Classes

what those names suggest. For example, we can derive classes from Shape to represent
squares and circles.
class Square(Shape ):
def __init__(self , name , side ):
super (). __init__(name)
self.side = side

def perimeter(self ):
return 4 * self.side

def area(self ):
return self.side ** 2

class Circle(Shape ):
def __init__(self , name , radius ):
super (). __init__(name)
self.radius = radius

def perimeter(self ):
return 2 * math.pi * self.radius

def area(self ):
return math.pi * self.radius ** 2

Since squares and circles have the same methods, we can use them interchangeably.
This is called polymorphism, and it reduces cognitive load by allowing the people using
related things to ignore their differences:
examples = [Square ("sq", 3), Circle ("ci", 2)]
for thing in examples:
n = thing.name
p = thing.perimeter ()
a = thing.area ()
print(f"{n} has perimeter {p:.2f} and area {a:.2f}")

sq has perimeter 12.00 and area 9.00

ci has perimeter 12.57 and area 12.57

But how does polymorphism work? The first thing we need to understand is that a func-
tion is an object. While the bytes in a string represent characters and the bytes in an image
represent pixels, the bytes in a function are instructions (Figure 2.1). When Python exe-
cutes the code below, it creates an object in memory that contains the instructions to print
a string and assigns that object to the variable example:
def example ():
print ("in example ")

We can create an alias for the function by assigning it to another variable and then call the
function by referencing that second variable. Doing this doesn’t alter or erase the connection
between the function and the original name:
alias = example
alias ()

in example

We can also store function objects in data structures like lists and dictionaries. Let’s
write some functions that do the same things as the methods in our original Python and
store them in a dictionary to represent a square (Figure 2.2):
2.1 Objects 9

bytes

74 69 73 27 61 20 6C 6C 6A 20 73 75 20 74 79 62 65 74 0A 73

as text as instructions
as image old_x = x
"it's all just bytes"
x=2*x+1

Figure 2.1: Bytes can be interpreted as text, images, instructions, and more.

name "sq"
side 2
square
perim square_perim()
area square_area()

name "ci"
radius 3
circle
perim circle_perim()
area circle_area()

Figure 2.2: Using dictionaries to emulate objects.

def square_perimeter(thing ):
return 4 * thing [" side "]

def square_area(thing ):
return thing [" side "] ** 2

def square_new(name , side ):

return {
"name ": name ,
"side ": side ,
"perimeter ": square_perimeter ,
"area ": square_area
}

If we want to use one of the “methods” in this dictionary, we call it like this:
def call(thing , method_name ):
return thing[method_name ]( thing)

examples = [square_new ("sq", 3), circle_new ("ci", 2)]

for ex in examples:
n = ex[" name "]
p = call(ex , "perimeter ")
a = call(ex , "area ")
print(f"{n} {p:.2f} {a:.2f}")

The function call looks up the function stored in the dictionary, then calls that function with
the dictionary as its first object; in other words, instead of using obj.meth(arg) we use
obj["meth"](obj, arg). Behind the scenes, this is (almost) how objects actually work.
10 2 Objects and Classes

We can think of an object as a special kind of dictionary. A method is just a function that
takes an object of the right kind as its first parameter (typically called self in Python).

2.2 Classes
One problem with implementing objects as dictionaries is that it allows every single object
to behave slightly differently. In practice, we want objects to store different values (e.g.,
different squares to have different sizes) but the same behaviors (e.g., all squares should
have the same methods). We can implement this by storing the methods in a dictionary
called Square that corresponds to a class and having each individual square contain a ref-
erence to that higher-level dictionary (Figure 2.3). In the code below, that special reference
uses the key "_class":
def square_perimeter(thing ):
return 4 * thing [" side "]

def square_area(thing ):
return thing [" side "] ** 2

Square = {
"perimeter ": square_perimeter ,
"area ": square_area ,
"_classname ": "Square"
}

def square_new(name , side ):

return {
"name ": name ,
"side ": side ,
"_class ": Square
}

Calling a method now involves one more lookup because we have to go from the object
to the class to the method, but once again we call the “method” with the object as the first
argument:

Square
name "sq"
square side 2 _classname "square"
_class perim square_perim()
area square_area()

Circle
name "ci"
circle radius 3 _classname "circle"
_class perim circle_perim()
area circle_area()

Figure 2.3: Using dictionaries to emulate classes.

2.3 Arguments 11

def call(thing , method_name ):

return thing [" _class "][ method_name ]( thing)

examples = [square_new ("sq", 3), circle_new ("ci", 2)]

for ex in examples:
n = ex[" name "]
p = call(ex , "perimeter ")
a = call(ex , "area ")
c = ex[" _class "][" _classname "]
print(f"{n} is a {c}: {p:.2f} {a:.2f}")

As a bonus, we can now reliably identify objects’ classes and ask whether two objects are
of the same class or not by checking what their "_class" keys refer to.

Arguments vs. Parameters

Many programmers use the words argument and parameter interchangeably, but
to make our meaning clear, we call the values passed into a function its arguments
and the names the function uses to refer to them as its parameters. Put another way,
parameters are part of the definition, and arguments are given when the function is
called.

2.3 Arguments
The methods we have defined so far operate on the values stored in the object’s dictionary,
but none of them take any extra arguments as input. Implementing this is a little bit tricky
because different methods might need different numbers of arguments. We could define
functions call_0, call_1, call_2 and so on to handle each case, but like most modern
languages, Python gives us a better way. If we define a parameter in a function with a
leading *, it captures any “extra” values passed to the function that don’t line up with named
parameters. Similarly, if we define a parameter with two leading stars **, it captures any
extra named parameters:
def show_args(title , *args , ** kwargs ):
print(f"{ title} args '{args}' and kwargs '{kwargs }'")

show_args (" nothing ")

show_args ("one unnamed argument", 1)
show_args ("one named argument", second ="2")
show_args ("one of each", 3, fourth ="4")

nothing args '()' and kwargs '{}'

one unnamed argument args '(1,)' and kwargs '{}'
one named argument args '()' and kwargs '{'second ': '2'}'
one of each args '(3,)' and kwargs '{'fourth ': '4'}'

This mechanism is sometimes referred to as varargs (short for “variable arguments”).

A complementary mechanism called spreading allows us to take a list or dictionary full of
arguments and spread them out in a call to match a function’s parameters:
12 2 Objects and Classes

def show_spread(left , middle , right ):

print(f"left {left} middle {middle} right {right }")

all_in_list = [1, 2, 3]
show_spread (* all_in_list)

all_in_dict = {" right ": 30, "left ": 10, "middle ": 20}
show_spread (** all_in_dict)

left 1 middle 2 right 3

left 10 middle 20 right 30

With these tools in hand, let’s add a method to our Square class to tell us whether a
square is larger than a user-specified size:
def square_larger(thing , size ):
return call(thing , "area ") > size

Square = {
"perimeter ": square_perimeter ,
"area ": square_area ,
"larger ": square_larger ,
"_classname ": "Square"
}

The function that implements this check for circles looks exactly the same:
def circle_larger(thing , size ):
return call(thing , "area ") > size

We then modify call to capture extra arguments in *args and spread them into the function
being called:
def call(thing , method_name , *args ):
return thing [" _class "][ method_name ](thing , *args)

Our tests show that this works:

examples = [square_new ("sq", 3), circle_new ("ci", 2)]
for ex in examples:
result = call(ex , "larger", 10)
print(f"is {ex['name ']} larger? {result }")

is sq larger? False
is ci larger? True

However, we now have two functions that do exactly the same thing—the only difference
between them is their names. Anything in a program that is duplicated in several places
will eventually be wrong in at least one, so we need to find some way to share this code.

2.4 Inheritance
The tool we want is inheritance. To see how this works in Python, let’s add a method called
density to our original Shape class that uses other methods defined by the class
Random documents with unrelated
content Scribd suggests to you:
unaware. Round the two which contain water there are some rude
stone water troughs, which may be of any age.
These being the limits of the country, let us return again to a
consideration of its physical aspects.
The physical features of the country naturally depend upon its
geological formation. The ranges of hills, east and west of Jordan,
are formed almost entirely of beds of cretaceous limestone, which
were once continuous. The Jordan Valley coincides with a line of
fault; that is to say, the rocky strata cracked in an irregular line from
north to south, and the country west of this fault sank down bodily,
so that the higher strata of rocks on that side abut now against the
lower strata on the eastern side. With this depression to begin with,
the rains and torrents have gradually sculptured the valley into its
present form.
The maritime district of Palestine, stretching from the base of
Carmel southwards by Joppa and Gaza to the Desert of Beersheba,
consists of a series of low hills from 300 feet to 400 feet high,
separated by valleys and alluvial plains extending inland to a varying
distance. The coast line is bordered by a line of sand-hills, which,
when unrestrained by some physical barrier, are ever moving inland
with disastrous effect. The district is largely composed of beds of
sand and gravel, which have once been the bed of the outer sea;
while along the line of many of the rivers and streams a deposit of
rich loam of a deep brown colour covers considerable areas, and
yields abundant crops of wheat and maize to the cultivators.
Professor Edward Hull, the eminent geologist, who was
commissioned by the Palestine Exploration Society to investigate the
geology of the Desert and the Holy Land, reported the results to the
Committee, in an elaborate Memoir, in which he treats of the
maritime district, the table-land of Western Palestine and the Tih
Desert, the depression of the Jordan Valley and its continuation
southward to the Gulf of Akabah, the elevated plateau east of
Jordan, and the mountainous tract of the peninsula of Sinai. Utilising
the labours of his predecessors, Russeger, Fraas, Lartet, Vignes, &c.,
he sometimes confirms their results, and sometimes adds to our
knowledge.
 GEOLOGICAL SKETCH MAP
of
SINAI & PALESTINE
(based chiefly upon the Maps of M.M. Lartet, Hull & Zittel.)
The figures represent deviations above the sea level in English feet; those with a
minus mark represent depressions below sea level.

By the kindness of Mr W. H. Hudleston, F.R.S., and Secretary of

the Geological Society, I am able to illustrate this chapter with a
geological map based chiefly on the maps of Lartet, Hull, and Zittel.
To a great extent it tells its own story regarding the features of the
country, and the rocks and formations of which the region is
constructed. The oldest rocks occupy the greater portion of the
Sinaitic peninsula, as well as the mountains bordering the Gulf of
Akabah, and extending northward along the eastern side of the
Wady el Arabah. They consist of granitic, gneissose and schistose
rocks, amongst which have been intruded great masses of red
porphyry, dark green-stone, and other igneous rocks in the form of
dykes, veins, and bosses. These rocks are probably among the
oldest in the world. After these ancient rocks had been consolidated
they were subjected to a vast amount of erosion, and were worn
into very uneven surfaces, over which the more recent formations
were spread; first filling up the hollows with the lower strata, and
ultimately covering even the higher elevations as the process of
deposition of strata went on. The oldest of these formations is the
Red Sandstone and Conglomerate, which Professor Edward Hull calls
the “Desert Sandstone” formation. It forms a narrow strip along the
margin of the old crystalline rocks. It is capped with the fossiliferous
limestone of the Wady Nash, which shows it to belong to the
Carboniferous period—in fact to be the representative of the
Carboniferous Limestone of Europe and the British Isles. It is also
found east of the Arabah Valley and amongst the mountains of Moab
east of the Ghor. This is succeeded by another Sandstone formation,
more extensively distributed than the former. It belongs to a much
more recent geological period, namely, the Cretaceous; and is the
representative of the “Nubian Sandstone” of Roziere, so largely
developed in Africa, especially in Nubia and Upper Egypt. This is
succeeded by the Cretaceous and Nummulitic Limestone formations,
which occupy the greater part of the map, forming the great table-
land of the Tih, from its western escarpment to the borders of the
Arabah Valley, and stretching northward throughout the hill country
of Judea and Samaria into Syria and the Lebanon.
On the east of the Jordan Valley the Cretaceous Limestone forms
the table-lands of Edom and Moab: as far north as the Hauran and
Jaulan, where the limestone passes below great sheets of basaltic
lava. The Cretaceous Limestone represents the Chalk formation of
Europe and the British Isles.
Although the Cretaceous Limestone belongs to the Secondary
period, and the Nummulitic Limestone to the Tertiary, they are very
closely connected in Palestine, as far as their mineral characters are
concerned; and they both contain beds or bands of flint and chert.

GENERALISED GEOLOGICAL SECTION ACROSS PALESTINE.

o, Level of the Mediterranean: a, bed of the maritime plains; m, old lacustrine
deposits of the Dead Sea basin; n, deposits now forming beneath the Dead Sea;
p, tufaceous deposits of hot springs; h, basalt.

The Cretaceous Limestone underlies nearly the whole of the

Jordan and Arabah Valleys, although concealed by more recent
deposits, and is broken off along the line of the great Jordan Valley
fault against older formations. In other words, on the west we have
strata of the age of the English chalk, which dip down very suddenly
towards the centre of the valley. On the east we have the Nubian
Sandstone, with hard limestone above it geologically coeval with our
greensand. It is entirely owing to the presence of this leading line of
fracture and displacement, and the subsequent denudation of strata,
that this great valley exists, and that the eastern side is so
mountainous and characterised by such grand features of hill and
dale.
These limestones pass under a newer formation of Calcareous
Sandstone in the direction of the Mediterranean, a formation
probably of Upper Eocene age, and called by Hull the “Calcareous
Sandstone of Philistia.”
The formations next in order consist of raised beaches and sea-
beds along the coast, and of lake-beds in the Ghor and Jordan
Valley; and these bring us, geologically, much nearer to our own
time.
Not only do the physical features of a country depend upon its
geological formation, but it cannot be questioned that the character
and mode of life of the inhabitants are moulded or modified by the
physical features. It is remarked by Professor Edward Hull that the
mild patient character of the Egyptian cultivator befits the nature of
that wide alluvial tract of fertile land which is watered by the Nile.
The mountainous tracts of the Sinaitic peninsula, formed of the
oldest crystalline rocks of that part of the world, have become the
abode of the Bedouin Arab, the hardy child of nature, who has
adapted himself to a life in keeping with his wild surroundings. The
great table-land of the Tih, less rugged and inhospitable than the
mountainous parts of Sinai and Serbal, supports roving tribes, partly
pastoral, and gradually assimilating their habits to the Fellahin of
Philistia and of Palestine, who cultivate the ground and rear large
flocks and herds.
[Authorities and Sources:—Smith’s “Dictionary of the Bible.”
Survey of Western Palestine, Memoir on the Geology. Dr Edward
Hull. “The Geology of Palestine.” Wilfred H. Hudleston, F.R.S. “Rob-
Roy on the Jordan.” John Macgregor.]
 3. The Dead Sea, Salt Sea, or Sea of Lot.

It is pointed out by Sir George Grove that the name “Dead Sea”
never occurs in the Bible, and appears not to have existed until the
second century after Christ. It originated in an erroneous opinion,
and there can be little doubt that to the name are due in a great
measure the mistakes and misrepresentations which were for so
long prevalent regarding this lake, and which have not indeed yet
wholly ceased to exist. In the Old Testament it is called the Salt Sea,
and the Sea of the Plain (Arabah). By the Arabs it is called El Bahr
Lut (the Sea of Lot).
The Salt Sea lies in the deepest part of the great Jordan-Arabah
depression, and the ground rises to the south of it, as well as in all
other directions. It was shown, in fact, by Colonel Kitchener’s survey
of the Arabah that the bed of the valley, for the most part, is raised
above the level of the Gulf of Akabah. From the border of the Dead
Sea southward the ground rises but little for 10 miles, but then
begins to rise rapidly, so that at a distance of about 40 miles it is as
high as the sea level at Akabah; and 29 miles further south it is 660
feet above that level.
The Jordan Valley, as already stated, coincides with a great fault
in the strata. This had been recognised by Lartet, Tristram, Wilson,
and others; and Professor Hull has traced the continuation of this
fracture, at the base of the Edomite mountains along the Arabah
Valley. He agrees with Lartet in thinking that the waters of the
Jordan Valley have not flowed down into the Gulf of Akabah since
the land emerged from the ocean. The disconnection of the inner
waters from the outer is a very ancient event, dating back to
Miocene times.
The River Jordan, throughout its course, from the Sea of Tiberias
to the Salt Sea, cuts its channel through alluvial terraces, consisting
of sand, gravel, and calcareous marl, which sometimes contain
shells, semi-fossilised, but of species still living in the lakes of
Tiberias and Huleh. These terraces are continuous round the shores
of the Salt Sea, and between the base of the cliffs of Jebel Karantul,
near Jericho, and the fords of the Jordan, three of them may be
observed,
the first being at a level of 650 to 600 feet,
the second being at a level of 520 to 250 feet,
the third being at a level of 200 to 130 feet

and below the last named is the alluvial flat, liable to be flooded on
the rise of the waters. The upper surfaces and outer margins of
these terraces indicate successive stages, at which the waters have
rested in sinking down to their present level. Originally they reached
a level somewhat over that of the Mediterranean, and at that time a
great inland lake extended from Lake Huleh southwards into the
Arabah Valley, its length being about 200 miles.
In the Jordan Valley, the upper terrace, at the foot of the hills, is
called the Ghor, and it is to be distinguished from the Zor, or bottom
of the valley, in which the channel of the river, cut still deeper,
meanders.
The Salt Sea itself is enclosed on all sides by terraced hills, except
towards the north, where it receives the waters of the Jordan. In
rising gradually out of the ocean, the region appears to have rested
several times at successive levels, and the sea left its mark in
deposits of marl, gravel, and silt. Beyond the southern end of the
Salt Sea the banks of the Ghor rise in the form of a great white
sloping wall, to a height of about 600 feet above the plain, and are
formed of horizontal courses of sand and gravel, resting on white
marl and loam. This mural wall sweeps round in a semicircular form
from side to side of the Ghor. The upper surface is nearly level
(except where broken into by river channels), and from its base
stretches a plain covered partly, over the western side, by a forest of
small trees and shrubs, and partly by vegetation affording pasturage
to the numerous flocks of the Arabs, who settle down here during
the cooler months of the year. It is impossible to doubt that at no
remote period the waters of the Salt Sea, though now distant some
10 miles, washed the base of these cliffs, and a rise of a few feet
would submerge this verdant plain, and bring back the sea to its
former more extended limits.
From this position also, the white terrace of Jebel Usdum—“the
salt mountain” where the Crusaders wrongly placed Sodom—is seen
projecting from the sides of the loftier limestone terraces of the
Judæan hills. Towards the east, similar terraces of whitish alluvial
deposits are seen clinging to the sides of the Moabite hills, or
running far up the deep glens which penetrate the sides of the great
table-land. In these terraces, the upper surfaces of which reach a
level of about 600 feet above the waters of the Salt Sea, we behold
but the remnants of an ancient sea-bed, which must originally have
stretched from side to side.
Eight hundred feet higher than these terraces there are others
composed of marl, gravel, and silt, through which the ravines of
existing streams have been cut; and this indicates that the level of
the Salt Sea stood at one time 100 feet higher than the waters of
the Mediterranean stand now.
Origin of the saltness of the Dead Sea.—It has been generally
recognised that the waters of lakes which have no outlet ultimately
become more or less saline. Of these the most important in the old
world are the Caspian, the Sea of Aral, Lakes Balkash, Van, Urumiah,
and, lastly, the Dead Sea, or as it was originally called, “the Salt
Sea.” “The Caspian,” says Professor Hull, “owing to its great extent
and other causes, is but slightly saline; but that with which we have
here to deal is the most saline of all. It is probable that the water of
the ocean itself has become salt owing to the same cause which has
produced saltness in the inland lakes, as it may be regarded as a
mass of water without an outlet. The cause of the saltness in such
lakes I now proceed to explain.
“It has been found that the waters of rivers contain, besides
matter which is in a state of mechanical suspension, carbonates of
lime and magnesia, and saline ingredients in a state of solution; and
as those lakes which have an outlet, such as the Sea of Galilee, part
with their waters and saline ingredients as fast as they receive them,
the waters of such lakes remain fresh. It is otherwise, however, with
regard to lakes which have no outlet. In such cases the water is
evaporated as fast as it is received; and as the vapour is in a
condition of purity, the saline ingredients remain behind. Thus the
waters of such a lake tend constantly to increase in saltness, until a
state of saturation is attained, when the excess of salt is
precipitated, and forms beds at the bottom of the lake. The contrast
presented by the waters of the Sea of Galilee on the one hand, and
those of the Dead Sea on the other, though both are fed by the
same river, is a striking illustration of the effects resulting from
opposite physical conditions. In the former case, the waters are
fresh, and abound in fishes and molluscs; in the latter, they are so
intensely salt that all animal life is absent.
“The increase of saltness in the waters of the Dead Sea has
probably been very slow, and dates back from its earliest condition,
when its waters stretched for a distance of about 200 miles from
north to south....
“The excessive salinity of the waters of the Dead Sea will be
recognised from a comparison with those of the Atlantic Ocean.
Thus, while the waters of the ocean give six pounds of salt, &c., in a
hundred pounds of water, those of the Dead Sea give 24·57 pounds
in the same quantity; but in both cases the degree of salinity varies
with the depth, the waters at the surface being less saline than
those near the bottom....
“As to the depth of the waters:—The floor of the Dead Sea has
been sounded on two occasions: first, by the Expedition under
Lieutenant Lynch in 1848, and secondly, by that under the Duc de
Luynes. In the former case the maximum depth was found to be
1278 feet; in the latter 1217 feet, being close approximations to
each other. We may therefore affirm that the floor of the lake
descends to nearly as great a depth below its surface as the surface
itself below the level of the Mediterranean Sea.
“The section given by Lynch indicates that the place of greatest
depth lies much nearer the Moabite than the Judæan shore, and the
descent from the base of the Moabite escarpment below Jebel
Attarus and between the outlets of the Wâdies Mojeb and Zerka
Maïn, is very steep indeed. The deepest part of the trough seems to
lie in a direction running north and south, at a distance of about 2
miles from the eastern bank; and while the ascent towards this bank
is rapid, that towards the Judæan shore on the west is comparatively
gentle. The line of this deep trough seems exactly to coincide with
that of the great Jordan Valley fault. From the bottom of the deeper
part, the sounding line brought up specimens of crystals of salt
(sodium-chloride), and it can scarcely be doubted that a bed of this
mineral, together with gypsum, is in course of formation over the
central portions of the Dead Sea.”
[Authorities and Sources:—“Memoirs of the Survey: Geology”, Dr E. Hull.
Smith’s “Dict. of Bible.” “Tent Work in Palestine.” By Major Conder, R.E.]

4. The Cities of the Plain.

There is now a general consent that Sodom and Gomorrah,

Admah and Zeboim were situated north of the Dead Sea, in the
Kikkar or Plain of the Jordan. There are old maps which represent
these cities as situated at the bottom of the Dead Sea waters, and
yet enveloped in flames! Popular ignorance imagines that the
bitumen which rises to the surface of the waters is a relic of the
agency which effected the destruction. And until recently even the
best scholars supposed the cities to lie beneath the shallow part of
the sea, south of the Lisan peninsula. All such theories are disproved
by the geological investigation, which shows that the Dead Sea is
much older than any date which can be assigned to the destruction
of the cities, and that the surface of the water has been constantly
diminishing in area and sinking to lower levels.
There is nothing in the Bible which should lead us to look for the
cities south of the Dead Sea, where the Crusaders placed them, or
east of it, or anywhere but north and in the Kikkar. When Abraham
and Lot talked together concerning the disputes between their
herdsmen, and decided to go different ways with their flocks, “Lot
lifted up his eyes and beheld all the Plain of the Jordan, that it was
well watered ... until thou comest unto Zoar.” It was clearly shown
by Sir George Grove, in Smith’s “Dictionary of the Bible,” that the
Plain of the Jordan here spoken of is not the Arabah, in which the
Dead Sea reposes, but the Kikkar or “Round” of country north of it.
The position of Abraham and Lot at the time was on a mount east of
Bethel; and as the site of Bethel is known, it was not difficult to find
the mount east of it. It was reasonably identified by Rev. Canon
Williams, and his conclusions were confirmed in 1865 by Colonel Sir
C. Wilson. It has been shown that if the cities had been south of the
Dead Sea, human vision could not possibly have extended so far, to
distinguish anything. But north of the sea, in the Round or Plain, Lot
would be able to perceive them. Accordingly, when the friendly
conference ended, he journeyed eastward from the mount near
Bethel, in order to reach his new home in Sodom.
The vision of Lot had extended across the plain, to Zoar and no
farther, because the plain was bounded by the high mountains of
Moab. Dr Tristram believes that he has identified Zoar, the fifth city
of the Plain, the “little city” to which Lot fled after the convulsion.
Standing on Mount Nebo, he detected the ruins a little in front of
him, almost in a line with Jericho. The ruins were on a low brow of
ground, and thus correspond to the description that Lot rested in
this city on his way to the mountains, and afterwards went up into
the mountain and dwelt in a cave. The ruins are still called Ziara,
which does not differ much from the Greek spelling Ζωαρα, nor very
widely from the Hebrew.
Is it possible to discover any relics of the four larger cities?
Although destroyed by fire, they may not have been utterly
annihilated, any more than Pompeii; but if their remains are hiding
beneath the dust, the dust keeps its secret well. Major Conder rode
day by day over almost every acre of ground between Jericho and
the Dead Sea, and could not detect any mound or sign of a buried
city. The whole was a white desert, except near the hills, where rich
herbage grows after the rains. The time of year was most favourable
for such exploration, because no long grass existed to hide any
ruins. But in all that plain he found no ruin, except the old
monastery of St John and a little hermit’s cave.
This description leaves out of account a remarkable group of tells,
or mounds of earth and rubbish, strewn over with ruins, existing in
the neighbourhood of Jericho. They are seven in number, and one of
them is not far from Elisha’s Fountain, now called Ain es Sultan. One
would imagine that the exploration of these mounds might yield
valuable results; but nobody undertakes the work. It is true that
some excavations made by Sir Charles Warren only proved the
existence of sun-dried bricks; and because the mounds occur
generally where the soil is alluvial, Conder regards them as piles of
refuse bricks, and nothing more; but Sir J. W. Dawson, on visiting
the place, noticed numerous flint chips in the mound, and Sir C.
Warren, when presiding at my Guildford lecture, publicly expressed
the opinion that many small objects of great interest would probably
be found if the stuff were sifted.
But if the ruins of the Cities of the Plain are not discoverable, their
names appear to linger in the district, slightly disguised as Arabic
words, and applying to portions of the ground.
Conder justly remarks that the cities would probably be situated
near fresh-water springs, and the great spring of ’Ain Feshkhah, on
the north-west of the Dead Sea, is a probable site for one of them.
The great bluff not far south of the spring is called Tubk ’Amriyeh by
the Bedawin, and the neighbouring valley Wady ’Amriyeh. This word
is radically identical with the Hebrew Gomorrah, or Amorah as it is
spelt in one passage (Gen. x. 19), meaning, according to some
authorities, “depression,” according to others, “cultivation.”
Admah means “red earth,” a description which would hardly apply
to the ground near the Dead Sea. But there is no reason why all the
four cities should be close to the Dead Sea. A convulsion
overthrowing cities near the Sea would probably be felt a long way
up the Jordan Valley, owing to the line of fault. Conder has pointed
out, too, that the term Kikkar is applied in the Bible to the Jordan
Valley as far north as Succoth. A “city Adam” is noticed in the Book
of Joshua as being beside Zaretan; the name Ed Damieh applies to
the neighbourhood of the Jordan ford east of Kurn Surtabeh, about
23 miles up the valley; and it has always seemed possible to Conder
that Adam and Admah were one and the same. I would add a
suggestion of my own in support of the view that Admah was some
distance up the Jordan Valley. The passage Gen. x. 19 describes the
boundary of Canaan, beginning at Sidon, following the coast line to
Gaza, striking thence eastward to the Plain of the Jordan, and then
proceeding up the Jordan Valley to Dan or Lasha—and the passage
may be freely rendered thus,—“And the border of the Canaanite was
from Sidon; thence you go towards Gerar, as far as Gaza; thence you
go toward Sodom; then by Gomorrah and Admah and Zeboim, unto
Dan.”[14] As Gerar was beyond Gaza southward, the boundary only
went toward it; and as Sodom was beyond Jordan eastward, the
boundary only went toward Sodom; there was no need to say it
stopped at the river, for that was obvious. It then follows the course
of the river from the Dead Sea to the source of the stream. And then
the northern boundary is known without description. If this
rendering holds good, then Gomorrah was north-west of the Dead
Sea, on a line joining Gaza with Sodom; and the boundary of the
Canaanites, after reaching Gomorrah, touched Admah and Zeboim,
and continued northward to the grotto at Banias.
Zeboim means “hyenas,” and is identical with the Arabic Dub’a.
For this reason Conder asks whether it may not have been situated
at the cliff just above the plain, near the site of Roman Jericho, for
that is now called Shakh ed Dub’a, “lair of the Hyena.” If I am right
in my reading of Gen. x. 19, Zeboim should be northward of Admah
—unless two names so often coupled together may have their order
transposed. Grove reminds us that the Valley of Zeboim (the name
spelt a little differently) was a ravine or gorge apparently east of
Michmas, described in 1 Sam. xiii. 18. It appears to be overlooked in
the discussion that Zeboim is mentioned in Nehemiah xi. 34, in the
same group with Hadid, Lod, and Ono, among the places occupied
by the children of Benjamin, while in Neh. vii. 37, these three places
are named between Jericho and Senaah. But if the Lod in this
passage is to be regarded as Lydda in the Plain of Sharon, the
grouping of the places affords us no guidance.
Sodom alone, as Conder goes on to say, remains without a
suggestion, and he finds no trace of it west of the Jordan. He notes,
however, that the word Siddim is apparently the same with the
Arabic Sidd, which is used in a peculiar sense by the Arabs of the
Jordan Valley as meaning “cliffs” or banks of marl, such as exist
along the southern edge of the plains of Jericho, the ordinary
meaning being “dam” or obstruction. Thus the Vale of Siddim might
well, so far as its name is concerned, have been situated in the
vicinity of the northern shores of the Dead Sea.
Dr Selah Merrill, in his “East of the Jordan,” also discusses the site
of the Cities of the Plain. He says:—“Since Zoar was one of them, a
hint as to their situation may be derived from Gen. xiii. 10, where
Lot and Abraham are represented as standing on a hill near Bethel,
and looking down the Jordan Valley towards the Dead Sea. As this
verse is rendered in our English Bible, the meaning is not clear; but
it will become so when all the middle portion of the verse is read as
a parenthesis, as follows: ‘And Lot lifted up his eyes and beheld all
the Plain of Jordan (that it was well watered everywhere, before the
Lord destroyed Sodom and Gomorrah, even as the garden of the
Lord, like the land of Egypt), until thou comest to Zoar.’ The last
clause qualifies the first. Lot saw all the Plain of Jordan as far as
Zoar, or ‘until you come to Zoar.’ Zoar was both the limit of the plain
and the limit of vision in that direction, so far as the land was
concerned.”
Dr Merrill then shows that nothing could have been distinguished
at the southern end of the Dead Sea; and quotes early writers to
show that Zoar existed near the northern end.
Regarding the destruction of Sodom and Gomorrah, it is not
sufficient to say briefly that it was a miracle, and assume that no
further explanation can be given. A rain of brimstone and fire is
spoken of, and it is legitimate to look for the source of it. With the
instance of Pompeii in our minds it is natural to suggest volcanic
agency, especially as the region north-east of the Dead Sea affords
evidence of volcanic action. But Sir J. W. Dawson (a well-known
American geologist), in his volume on “Egypt and Syria,” ingeniously
argues for a petroleum explosion. The “slime pits” spoken of as
abounding in the Vale of Siddim (Gen. xiv. 10), he regards as
petroleum wells, and then traces a parallel as follows:—“Regions of
bitumen, like that of the Dead Sea, are liable to eruptions of a most
destructive character. Of these we have had examples in the oil
regions of America. In a narrative of one of these now before me,
and which occurred a few years ago, in the oil district of Petrolia, in
Canada, I read that a borehole struck a reservoir of gas, which
rushed upward with explosive force, carrying before it a large
quantity of petroleum. The gas almost immediately took fire, and
formed a tall column of flame, while the burning petroleum spread
over the ground and ignited tanks of the substance in the vicinity. In
this way a space of about fifteen acres was enveloped in fire, a
village was burned, and several persons lost their lives. The air
flowing toward the eruption caused a whirlwind, which carried the
dense smoke high into the air, and threw down burning bitumen all
round.
“Now, if we suppose that at the time referred to, accumulations of
inflammable gas and petroleum existed below the Plain of Siddim,
the escape of these through the opening of a fissure along the old
line of fault might produce the effects described—namely, a pillar of
smoke rising up to heaven, burning bitumen and sulphur raining on
the doomed cities, and fire spreading over the ground. The
attendant phenomenon of the evolution of saline waters, implied in
the destruction of Lot’s wife, would be a natural accompaniment, as
water is always discharged in such eruptions; and in this case it
would be a brine thick with mud, and fitted to encrust and cover any
object reached by it.”
An important note, with reference to the destruction of the Cities
of the Plain, appears in the statement in Gen. xiv., that the Vale of
Siddim had bitumen pits or wells, and that these were so abundant
or important as to furnish a place of retreat to, or to impede the
flight of, the defeated kings of Sodom and Gomorrah. These bitumen
pits have disappeared, unless their remains are represented by the
singular pits described by Dr Merrill as occurring near Wady Nimrim.
Their existence in the times of Abraham would bespeak a much
greater abundance of bituminous matter than that now remaining;
and it is possible that the eruption which destroyed the Cities of the
Plain may have, to a great extent, exhausted the supply of
petroleum.
“There is no reason to think” (adds Dr Dawson) “that the
destruction of Sodom and Gomorrah was connected with any
important change in the limits of the Dead Sea, though it is highly
probable that some subsidence of the valley took place, and may
have slightly affected its levels relatively to the Jordan and the sea;
but it would appear from Deut. xxix. 23, that the eruption was
followed by a permanent deterioration of the district by the saline
mud with which it was covered.”
In the Theological Monthly for May 1890, Rev. James Neil declares
that no bitumen pits are to be found anywhere in the neighbourhood
of the Jordan. The pits spoken of by Dr Selah Merrill were connected
with aqueducts, and used for purposes of irrigation. But the asphalt
thrown up from the bottom of the Dead Sea may have been
employed to render such pits watertight, and to that extent they
would be slime pits. He shows that such pits do exist in the Jordan
Valley, extending across it in long lines just north of the supposed
site of some of the Cities of the Plain; and it is a very curious fact
that the Bedawin, who are unacquainted with their nature and
purpose, have a legend connecting them with a great battle.
[Authorities and Sources:—Smith’s “Dict. of the Bible.” “Tent Work in
Palestine.” Major Conder, R.E. “The Land of Moab.” Rev. Canon Tristram, F.R.S.
“East of Jordan.” Dr Selah Merrill. “Egypt and Syria.” Sir J. W. Dawson.]

5. “Lot’s Wife.”
 In connection with the destruction of Sodom, the Bible mentions
the fate which overtook Lot’s wife, who “became a pillar of salt.” In
the Book of Wisdom also we read of the waste land that smoketh,
and plants bearing fruit that never come to ripeness, and a standing
pillar of salt—a monument of an unbelieving soul (Wisd. x. 7).
Josephus also says that he had seen it (Ant. i. 11, 4). The Arabs
have legends on the subject; and travellers now and again describe
the pillars of salt which have been pointed out to them, and to which
the legends attach. The stories are by no means modern. Major
Conder, in his “Syrian Stone Lore,” brings into brief compass the
notions of the Fathers of the Church on the subject. From an early
period “Lot’s wife” is mentioned as standing by the western shores
of the Dead Sea, and Antoninus Martyr is careful to combat the idea
that the pillar of salt was destroyed through its being constantly
licked by animals. Clemens Romanus had seen it; Irenæus also (IV.
xxxi. 3) mentions “Lot’s wife” as a pillar still standing. (Quoted by
Kitto, Cyclopæd. “Lot.”) So does Benjamin of Tudela, whose account
is more than usually circumstantial; and in later times Maundrell and
others. It seems possibly to be the natural pinnacle, now called
Karnet Sahsul Hameid, to which these writers refer. The feminine
nature of this statue was supposed to be still perceptible, in spite of
petrification.
Perhaps the best account of “Lot’s wife” is to be found in E. H.
Palmer’s “Desert of the Exodus,” where a coloured plate helps the
realisation.
“While with the Ghawárineh” (says Palmer) “we had heard
strange rumours that ‘a statue’ called ‘Lot’s wife’ existed on the
eastern shore of the Dead Sea, but none of them had ever seen it,
or could give us a satisfactory description of it. Making cautious
inquiries amongst the Beni Hamideh, we found that the statement
was correct, and after some little trouble, guides were procured who
offered to conduct us to the spot.... Our path led us to another
plateau, about 1000 feet above the Dead Sea, and on the extreme
edge of this was the object of which we were in search—Bint Sheikh
Lot, or ‘Lot’s wife.’ It is a tall isolated needle of rock, which does
really bear a curious resemblance to an Arab woman with a child
upon her shoulder. The Arab legend of Lot’s wife differs from the
Bible account only in the addition of a few frivolous details. They say
that there were seven Cities of the Plain, and that they were all
miraculously overwhelmed by the Dead Sea as a punishment for
their crimes. The prophet Lot and his family alone escaped the
general destruction; he was divinely warned to take all that he had
and flee eastward, a strict injunction being given that they should
not look behind them. Lot’s wife, who had on previous occasions
ridiculed her husband’s prophetic office, disobeyed the command,
and, turning to gaze upon the scene of the disaster, was changed
into this pillar of rock.
“Travellers in all ages have discovered ‘Lot’s wife’ in the pillars
which atmospheric influences are constantly detaching from the
great masses of mineral salt at the southern end of the Dead Sea,
but these are all accidental and transient. The rock discovered by us
does not fulfil the requirements of the Scriptural story, but there can
be no doubt that it is the object which has served to keep alive for
so many ages the local tradition of the event.
“The sun was just setting as we reached the spot; and the
reddening orb sank down behind the western hills, throwing a bridge
of sheeny light across the calm surface of the mysterious lake. As we
gazed on the strange statue-like outline of the rock—at first brought
out into strong relief against the soft yet glowing hues of the
surrounding landscape, and then mingled with the deepening
shadows, and lost amid the general gloom as night came quickly on,
we yielded insensibly to the influence of the wild Arab tale, and
could almost believe that we had seen the form of the prophet’s wife
peering sadly after her perished home in the unknown depths of that
accursed sea.”

6. The Natural History of Palestine, as dependent on its Physical

Geography.
 The gradual elevation of the countries of Egypt and Palestine,
inferred by Professor Hull from the geological facts, appears to be
borne out by a comparison of the fishes which inhabit respectively
the Lake of Galilee and the lakes of south-eastern Africa.
Josephus, after describing in glowing language the beauty and
fruitfulness of the country of Gennesaret, says, “For besides the
good temperature of the air, it is also watered from a most fertile
fountain. The people of the country call it Capharnaum. Some have
thought it to be a vein of the Nile, because it produces the Coracin
fish as well as that lake does which is near to Alexandria.”[15] The
truth turns out to be much stranger than Josephus imagined, for the
Sea of Galilee can claim affinity by its fishes with the Victoria
Nyanza. Rev. Canon Tristram, who more than any other traveller has
studied the natural history of the Holy Land, has made the
comparison in some detail, and made out the relationship of the
fishes beyond doubt. He declares that of all the forms of life in
Palestine the fishes are the most interesting. There are no fishes in
the Dead Sea; but there are fishes, chiefly Cyprinidæ, or of the
perch tribe, in the little streams and rivers close to the Dead Sea. “I
have seen the date palm absolutely dipping its fronds into the Dead
Sea as it hung over—for on the east side the date palm is very
luxuriant. On the eastern shores there is as wonderful an
exuberance of vegetable life as will be found anywhere on the face
of the earth. The plants are like hot-house plants growing wild. In
the warm waters entering to the sea there are small fishes of various
species. We found thirteen new kinds of fishes in the Jordan and its
affluents. Dr Günther of the British Museum kindly described them in
a paper in the ‘Proceedings of the Zoological Society of London,’ and
certainly such a discovery amply repaid our search.
“I wish now to point out the conclusions come to from these
fishes, for they are really the climax of the physical geography of the
Jordan Valley. The fishes found in the Sea of Galilee not only belong
for the most part to species different from those found in any stream
flowing into the Mediterranean, but they belong frequently to
different genera. Some years before, I brought home the type
specimen of a fish, the only species I could find in some salt lakes of
the Sahara, and Dr Günther declared it to be not only a new species
but a new genus. I remember Sir Charles Lyell observing, ‘You have
got there the last living representative of the Saharan ocean.’ We
found in the Sea of Galilee three more species of the same genus,
but each distinct. Speke brought back two species of the same
family from the Nyanza, and Dr Kirk has described several from the
Zambezi and the neighbouring region.
“Now we may see what this amounts to. We have got the same
genus of fishes represented in a variety of specific types from the
Sea of Galilee and the Jordan that are found in the feeders of the
Nile, and in the Central African lakes down to the Zambezi. The
conclusion is natural that all these fishes come from a common
origin, and that during the Tertiary period there was a chain of fresh-
water lakes, extending to the lakes in Africa, similar to the chain of
lakes in North America.
“We find in Palestine forty-three species of fishes, of which only
eight belong to the ordinary ichthyological fauna of the
Mediterranean rivers. But these belong to the rivers of the coast. In
the Jordan system only one species out of thirty-six belongs to the
ordinary Mediterranean fauna, viz., Blennius lupulus. Two others,
Chromis niloticus and Clarias macracanthus, are Nilotic. Seven other
species occur in other rivers of South-Western Asia, the Tigris,
Euphrates, &c. Ten more are found in other parts of Syria, chiefly in
the Damascus lakes, and the remaining sixteen species of the
families Chromidæ, Cyprinodontidæ, and Cyprinidæ, are peculiar to
the Jordan, its affluents, and its lakes. This analysis points at once to
the close affinity of the Jordan with the rivers of Tropical Africa. The
affinity is not only of species, but of genera, for Chromis and
Hemichromis are peculiarly Ethiopian forms, while the other species
are identical with, or very closely allied to, the fishes from other
fresh waters of Syria. But the African forms are a very large
proportion of the whole, and considering the difficulty of
transportation in the case of fresh water fishes, the peculiarities of
this portion of the fauna are of great significance.
“The fluviatile fishes claim special attention, dating, as they
probably do, from the earliest time after the elevation of the country
from the Eocene ocean. In the Foraminifera, mentioned above as
found in the Dead Sea sand, such as Gr. capreolus, we have the
relics of the inhabitants of that early sea. But of the living
inhabitants we must place the Jordanic fishes as the very earliest,
and these, we have seen, form a group far more distinct and
divergent from that of the surrounding region than in any other class
of existing life. During the epochs subsequent to the Eocene, owing
to the unbroken isolation of the basin, there have been no
opportunities for the introduction of new forms, nor for the further
dispersion of the old ones. These forms, as we have seen, bear a
striking affinity to those of the fresh-water lakes and rivers of
Eastern Africa, even as far south as the Zambezi. But the affinity is
in the identity of genera, Chromis and Hemichromis being exclusively
African, while the species are rather representative than identical.
“The solution appears to be that during the Meiocene and
Pleiocene periods the Jordan basin formed the northernmost of a
large system of fresh-water lakes, extending from north to south, of
which, in the earlier part of the epoch, perhaps the Red Sea, and
certainly the Nile Basin, the Nyanza, the Nyassa, and the Tanganyika
lakes, and the feeders of the Zambezi, were members. During that
warm period, a fluviatile ichthyological fauna was developed suitable
to its then conditions, consisting of representative, and perhaps
frequently identical species, throughout the area under
consideration.
“The advent of the glacial period was, like its close, gradual. Many
species must have perished under the change of conditions. The
hardiest survived, and some perhaps have been gradually modified
to meet those new conditions. Under this strict isolation it could
hardly be otherwise; and however severe the climate may have
been, that of the Lebanon, with its glaciers probably corresponding
with the present temperature of the Alps at a proportional elevation
(regard being had to the difference of latitude), the fissure of the
Jordan being, as we certainly know, as much depressed below the
level of the ocean as it is at present; there must have been an
exceptionally warm temperature in its waters in which the existing
ichthyological fauna could survive.”
Such facts as these tell us that Palestine is not to be regarded as
a European country, but rather as an African outlier, while it has also
strong affinities with Asia, as proved by others of these fishes. In
fact, it stands in the midst between three continents, and is, in a
very important sense, the centre of the world. Dr Tristram, our best
authority in this department, shows us how Palestine contains an
epitome of the life of the world, and does so just because it includes
almost every variety of climate.
Linnæus said that we know more of the botany and zoology of
farther India than we do of those of Palestine. It is pleasant to
reflect that, to some extent, this reproach has been removed. It
always entered into the plans of the Palestine Exploration Society to
study the natural history of the Holy Land; and although they have
not been able to equip and maintain a party of naturalists, charged
with this business alone, some of their officers have gathered
interesting facts incidentally. Other inquirers, like Rev. Wm.
Houghton and Mr Thaddeus Mason, have been usefully engaged on
the same work. Mr H. Chichester Hart, who accompanied Professor
E. Hull through the Arabah and Southern Palestine, has written an
interesting volume on “The Animals mentioned in the Bible.” But it is
to Rev. Dr Tristram we are chiefly indebted. The Memoirs of the
Survey include a magnificent volume on the “Fauna and Flora of
Western Palestine,” in which he works out his valuable series of
investigations, and besides giving facts and details, treats the
subject in a large philosophical way, as he does also in his lectures.
“You have on Lebanon and Hermon,” he says, “a climate like that of
the Alps, or two-thirds of the way up Mont Blanc. You have on the
tops of Lebanon and Hermon an almost arctic climate, and you have
a fauna and a flora (animals and plants) corresponding to that
climate. You know that when you descend a coal-pit 1300 feet deep
you get into a very warm temperature indeed. Now the Dead Sea is
1300 feet below the level of the Mediterranean, and the
consequence is that you have around the Dead Sea a tropical or
sub-tropical climate, and you have sub-tropical products.
“At the northern end of the Holy Land you find yourself at the
starting point of the Jordan, which, being 1000 feet above the
Mediterranean at the grotto of Banias, descends so rapidly that it is
only a few feet above the sea level at Lake Huleh. Mount Hermon
rises abruptly from its base near Lake Huleh (the ancient Waters of
Merom). Although Hermon is only 10,000 feet high, I am not aware
of any mountain which rises so suddenly or so directly from its base.
Take, for instance, Chamounix. If you want to go to the top of Mont
Blanc, you know that Chamounix is many hundred feet above the
platform of the Mediterranean. It is true that Mont Blanc is many
thousand feet higher than Mount Hermon, but from its immediate
base it is not so high. When you get up to the Grand Mulets you are
not so far from the summit of Mont Blanc as you are at Lake Huleh
from the summit of Hermon. The consequence of this is that you
have brought together in that spot a greater contrast of produce,
animal and vegetable, than I have found anywhere else. You have
the arctic climate of the north on the tops of the mountains, and a
tropical climate in the Jordan Valley, where, in the month of January,
I have been glad to sleep in the open air, the thermometer never
being below 80° at midnight. At the east and south you have the dry
sandy desert; so that you have four distinct climates within view of
each other. I can stand on any of the hills of Judea and see the
snow-capped tops of Hermon and Lebanon, and look over this vast
desert eastward and down to the seething tropical valley of the Dead
Sea.
“Now, with all that, there is nothing in the physical character of
that country which is striking or phenomenal, as people would call it.
It is about the most commonplace and ordinary country in the world
that I have ever seen. There are no startling features, but there is
endless variety in it, and I cannot help thinking that there is
something very providential in the extraordinary variety which is
brought together within a district of the Holy Land, which is not so
large as the six northern counties of England; because I remember
that it was chosen as the country in which was written a Book,
which was to be for the teaching and guidance of all mankind in
every country and in every age; and I know no spot in the world in
which there could have been found brought together so many
phenomena of Nature, maritime and desert, mountain and plain, hill
and valley, tropical, temperate, and arctic, as are brought together
there within the space of a few miles. And when I remember that
that Book was to be for the teaching of all men, for all time, I feel
that there is something providential in that ordering of circumstances
which led to the selection of the only spot, as far as we know, in the
whole world, in which there is such a great variety of objects for the
illustration, comparison, and elucidation of Holy Writ as in that
country of the Holy Land. Often, when I have been in that country,
on one of its hills, and have noticed the variety of scenery brought
into my view at one time, I have thought to myself, ‘What would the
Bible have been if its pages had been written by men who had lived
only in the monotonous valley of the Nile? What would they have
been able to pen in the way of illustration which would have come
home to the heart of the English peasant?’ Again, if that Book were
written by men who were only familiar with the phenomena of
Arabian deserts, how could it have come home to those who dwell
on the sea? Had it been written by inhabitants of tropical India, how
would it have come home to those who are familiar with ‘snow and
frost and vapour, fulfilling His will?’ In fact, there are illustrations
taken from every kind of natural phenomena, and yet none of them
are very marked or startling.”
[Authorities and Sources:—“Palestine in its Physical Aspects.” Rev. Canon
Tristram, F. R. S. Survey Memoirs: “The Fauna and Flora.” Rev. Canon
Tristram. “The Animals mentioned in the Bible.” Henry Chichester Hart, B.A.,
F.L.S.]

7. The Topographical Survey of Western Palestine.

 Before we can properly understand the history of any country we
must have before us an accurate map, showing its physical features
of mountain, plain, and river, and the relative positions of its cities
and important places. This is true in an unusual degree in the case
of Palestine, a country peculiar in its physical contrasts, and for more
than a thousand years the home of a peculiar people. The sacred
books of other religions—consisting greatly of rhapsodies, prayers,
and devotions—might have been written as well in one country as
another; but the Bible contains the history of a particular people,
occupying a definite district of country, fighting their battles, making
their journeys, and singing psalms oft suggested by their
surroundings. It is absolutely necessary for the student of Hebrew
history to make himself acquainted with Palestine geography and
topography. “The history assumes everywhere a knowledge of the
country, and the writer never stops to explain where the scene of
every episode occurs, except to name it as a spot already known.”
Yet, until lately, no accurate map of the country could be obtained—
because no scientific survey had been carried out. Bible towns and
villages had disappeared, and their sites were not known. The visitor
to Palestine, consulting Murray’s “Handbook” as his best guide,
found long columns of “places mentioned in Scripture, but not yet
identified”—Admah, Adullun, Debir, Edrei, Gallim, &c., &c. In going
up from Jaffa to Jerusalem he was shown a brook, and told that
David there selected the five smooth stones before his combat with
Goliath; but the brook was in the wrong locality. Down by the Jordan
he found the grave of Moses on the wrong side of the river. In
Galilee he was perplexed how to decide between two rival sites for
Cana, especially as the water-pots connected with the marriage feast
were to be seen at both places. General uncertainty attended his
footsteps throughout.
The people who did most to bring about this confusion in regard
to the sacred sites were the Crusaders. Knights and priests of the
twelfth century, arriving in Palestine, were strangers in the country,
and although enthusiastic they were ignorant and illiterate. They
used to land at Athlit, and journey thence to Nazareth or to
Jerusalem, fixing as many places en route as they could. Athlit itself
they regarded as the ancient Tyre! Meon, the home of Nabal, they
fixed close by, because Mount Carmel was not far off, and Abigail
came from Carmel. They did not recognise that the Carmel of Abigail
and Nabal was a city in the south of Judah. Knowing that
Capernaum was a fishing town, they placed it on the Mediterranean
coast and identified it with a fortress of their day, now the village
called Kefr Lam. These three places, which were shown to the
religious devotee as soon as he landed, are in reality many days’
journey apart. Caipha (Haifa) was shown as a place where Simon
Peter used to fish. Shiloh was south of Bethel, and was in fact the
mountain now called Nebi Samwil. Sychar and Shechem were one
and the same place. “The Quarantania or Kuruntul mountain” (says
Conder) “has, from the twelfth century down, been shown as the
place where our Lord retired for the forty days of fasting in the
desert. Near to it the Crusaders also looked for the ‘exceeding high
mountain’ whence the Tempter showed our Lord ‘all the kingdoms of
the world and the glory of them’ (Matt. iv. 8). Saewulf tells us that
the site of this mountain was 3 miles from Jericho. Fetellus places it
north of that town and 2 miles from Quarantania. The
measurements bring us to the remarkable cone called the Raven’s
Nest. The story is wonderfully descriptive of the simplicity of men’s
minds in the twelfth century, for the summit of the ‘exceeding high
mountain,’ whence all the kingdoms of the world were to have been
seen, is actually lower than the surface of the Mediterranean, and it
is surrounded on every side by mountains more than double its
height.”
Tradition having been shown to be untrustworthy, when
unsupported by other evidence, a general uncertainty prevailed with
regard to Scripture places. No traveller could believe what his guide
or guide book told him, and no student could have confidence in his
map. The labour of investigation was beyond the power of private
individuals; and no Government and no Society had ever sent out an
organized expedition. But now happily this reproach is removed. The
Committee of the Palestine Exploration Fund were able to send out
Major Conder, R.E., and Colonel Kitchener, R.E., and these officers,
with their little party, spent seven years in carrying out a
triangulation survey of the entire country west of the river Jordan.
As a result of their labours, followed up by much patient work at
home, we are now presented with a magnificent map of Western
Palestine, on the scale of one inch to the mile, as beautifully and
accurately executed as the ordnance map of England, with every
road and ruin marked, and every conspicuous object filled in; with
the hills and mountains correctly delineated and shaded, with the
rivers and brooks all running in the right directions; with every
vineyard, every spring of water, and almost every clump of trees set
down in its place, and with thousands of names that never appeared
on a Palestine map before. Moreover, while there are six hundred
and twenty-two Scripture names of places west of the Jordan, and
out of these three hundred and sixty were missing, the surveyors
have succeeded in finding one hundred and seventy-two of these. A
reduced map, on the scale of three-eighths of an inch to the mile,
has been prepared, and contains the Old Testament names and New
Testament names conspicuously marked, while other forms of the
map show the watershed and physical features of the country, or
give the divisions of the land and the Arabic names of places in use
to-day.
There could be no better aid in studying the Scriptures than to
have such maps by our side; for whether we read of the marching
and counter-marching of armies; of the positions taken up before a
battle; of the direction taken by the retreating foe; the sites selected
for places of worship; the journeys of prophets of the Old
Testament, or of Jesus and his disciples in the New, so much
depends upon the relative positions of places, and their distances
one from another, that we necessarily lose a part of the meaning,
and miss a portion of the enjoyment unless we have a correct map
by our side.
The best modern map of the Holy Land, previous to that prepared
by the Palestine Exploration Fund, was the work of Van de Velde, a
careful and scientific traveller and scholar. Van de Velde not only
took observations himself, but laid down on his map all the
observations made by previous travellers. Yet, when at the annual
meeting of the Palestine Exploration Fund in 1886, a portion of Van
de Velde’s map was shown on an enlarged scale, side by side with
the same portion of the Society’s map, similarly enlarged, the
contrast was striking. The first, with its hills roughly sketched in, its
valleys laid down roughly, and its inhabited places, villages, or ruins,
gave all that was known of this piece of country before the Survey. It
was on such a map as this, the best at the time, because the most
faithful, that the geographical student had to work. There was little
use, from a geographical point of view, in consulting previous books
of travel, because Van de Velde had gleaned from them all their
geographical facts. Yet hardly any single place was laid down
correctly; none of the hill shading was accurate; the course of the
rivers and valleys was not to be depended upon; the depression of
the Lake of Galilee was variously stated; distances were estimated
by the rough reckoning of time taken from place to place; and the
number of names was only about eighteen hundred, whereas the
large map of the Palestine Exploration Society contains ten
thousand.[16]
PHYSICAL MAP of PALESTINE
 [Authorities and Sources:—“Tent Work in Palestine.” Major Conder, R. E.
“Twenty-one Years’ Work in the Holy Land.” P. E. Fund. “Quarterly Statements
of the P. E. Fund.”]

8. Israel’s Wars and Worship, considered in connection with the

Physical Features of the Country.

The Wars.

Now that we possess a detailed and accurate map of the Holy

Land we are in a position to study with advantage the conquest of
the country by Joshua, and to appreciate the motives of strategy
and policy displayed in the successive phases of Israel’s wars and
worship.
The twelve tribes, coming out of the wilderness, encamped in the
Plain of the Jordan, opposite Jericho. While they rested there, Balak,
king of Moab, alarmed by their numbers, and uncertain as to their
intentions, sent to Mesopotamia for Balaam, to come and curse
them. Balaam ascended Mount Peor (sacred to Baal Peor, i.e., Baal
the Opener) and was constrained to bless them, and speak of them
as “a people that dwell alone—not reckoned among the nations”
(Num. xxiii. 9).
Under Moses the Israelites conquered the country east of Jordan.
The gorge of the Arnon, 2000 feet deep, and with almost
perpendicular sides, was a natural boundary for the Moabites.
Sometimes, indeed, they possessed territory north of it; but since it
would take a traveller several hours to cross at the easiest parts, it
was a natural boundary. The district between the Arnon and the
Jabbok, Moses wrested from Sihon, king of Heshbon. And then, with
the aid of the Ammonites, he conquered the country north of the
Jabbok, from Og, the king of Bashan. These lands were not divided
among all the tribes of Israel, but were given to Reuben, Gad, and
half the tribe of Manasseh as their portion, for it was planned and
intended that the country west of the Jordan should be conquered
and given to the rest.
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebookname.com