Chapter 2.15

Documentation and Inspection

"This non-system holds together by having no togetherness, no uniformity, never seeking perfection, no Utopias---just answers good enough to get by, with lots of looseness and room for many ways and attitudes."

Robert A. Heinlein, Glory Road

When exploring a new library, documentation of the source code is invaluable. In some cases, the ultimate failure or success of a project can rest squarely on how well it has been documented---but lets say you write a library that has no competition, so people use it anyway because it's the only tool available. How much time and effort can you save answering questions and solving issues, by providing clear and instructive documentation, use-cases, and tutorials up-front?

The same goes for commenting your source-code; sometimes you might think your code is perfectly self-explanatory, but then six-months down the road---or even the next day!---you come back to your code and have no idea what you were thinking when you implemented a critical function to your system. Imagine how a newcomer to your source code might feel!

Another problem can be the opaqueness of objects. In any serious project, you have all these complex, structured objects running in your program---they could be from any number of libraries, each of which could be using very different conventions. If only there was some way to see inside these black boxes!

Oh right, this is Lisp. You can get into the REPL of any running Lisp application and inspect everything.

Exercise 2.15.1

Documentation and Comments

Exercise 2.15.2

More Documentation and Comments

Exercise 2.15.3

Even More Documentation and Comments

Exercise 2.15.4


Exercise 2.15.5

Unreadable Objects

Exercise 2.15.6

Modifying the Lisp Printer

Exercise 2.15.7


Exercise 2.15.8


Exercise 2.15.9


Exercise 2.15.10


Exercise 2.15.11


Exercise 2.15.12


Extra Credit Exercise 2.15.13

Documentation and Inspection in Emacs+SLIME

results matching ""

    No results matching ""