Ruby Best Practices

Edition 1

Gregory Brown

Sada Preisch

David Futato

Robert Romano

Ellen Troutman Zaig

Karen Montgomery

Yukihiro “Matz” Matsumoto

Copyright © 2009 Gregory Brown

Legal Notice

Printed in the United States of America.

Legal Notice

[M]

Legal Notice

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or .

Legal Notice

O’Reilly and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Ruby Best Practices, the image of a green crab, and related trade dress are trademarks of O’Reilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

Legal Notice

While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. In March 2010, this work will be released under the Creative Commons Attribution-Noncommercial-Share Alike 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, 171 2nd Street, Suite 300, San Francisco, California, 94105, USA.

Foreword
Preface
1. Audience
2. About This Book
3. Conventions Used in This Book
4. Using Code Examples
5. Safari® Books Online
6. How to Contact Us
7. Acknowledgments
1. Driving Code Through Tests
1.1. A Quick Note on Testing Frameworks
1.2. Designing for Testability
1.3. Testing Fundamentals
1.3.1. Well-Focused Examples
1.3.2. Testing Exceptions
1.3.3. Run the Whole Suite at Once
1.4. Advanced Testing Techniques
1.4.1. Using Mocks and Stubs
1.4.2. Testing Complex Output
1.5. Keeping Things Organized
1.5.1. Embedding Tests in Library Files
1.5.2. Test Helpers
1.5.3. Custom Assertions
1.6. Conclusions
2. Designing Beautiful APIs
2.1. Designing for Convenience: Ruport’s Table( ) feature
2.2. Ruby’s Secret Power: Flexible Argument Processing
2.2.1. Standard Ordinal Arguments
2.2.2. Ordinal Arguments with Optional Parameters
2.2.3. Pseudo-Keyword Arguments
2.2.4. Treating Arguments As an Array
2.3. Ruby’s Other Secret Power: Code Blocks
2.3.1. Working with Enumerable
2.3.2. Using Blocks to Abstract Pre- and Postprocessing
2.3.3. Blocks As Dynamic Callbacks
2.3.4. Blocks for Interface Simplification
2.4. Avoiding Surprises
2.4.1. Use attr_reader, attr_writer, and attr_accessor
2.4.2. Understand What method? and method! Mean
2.4.3. Make Use of Custom Operators
2.5. Conclusions
3. Mastering the Dynamic Toolkit
3.1. BlankSlate: A BasicObject on Steroids
3.2. Building Flexible Interfaces
3.2.1. Making instance_eval( ) Optional
3.2.2. Handling Messages with method_missing( ) and send( )
3.2.3. Dual-Purpose Accessors
3.3. Implementing Per-Object Behavior
3.4. Extending and Modifying Preexisting Code
3.4.1. Adding New Functionality
3.4.2. Modification via Aliasing
3.4.3. Per-Object Modification
3.5. Building Classes and Modules Programmatically
3.6. Registering Hooks and Callbacks
3.6.1. Detecting Newly Added Functionality
3.6.2. Tracking Inheritance
3.6.3. Tracking Mixins
3.7. Conclusions
4. Text Processing and File Management
4.1. Line-Based File Processing with State Tracking
4.2. Regular Expressions
4.2.1. Don’t Work Too Hard
4.2.2. Anchors Are Your Friends
4.2.3. Use Caution When Working with Quantifiers
4.3. Working with Files
4.3.1. Using Pathname and FileUtils
4.4. The tempfile Standard Library
4.4.1. Automatic Temporary Directory Handling
4.4.2. Collision Avoidance
4.4.3. Same Old I/O Operations
4.4.4. Automatic Unlinking
4.5. Text-Processing Strategies
4.5.1. Advanced Line Processing
4.5.2. Atomic Saves
4.6. Conclusions
5. Functional Programming Techniques
5.1. Laziness Can Be a Virtue (A Look at lazy.rb)
5.2. Minimizing Mutable State and Reducing Side Effects
5.3. Modular Code Organization
5.4. Memoization
5.5. Infinite Lists
5.6. Higher-Order Procedures
5.7. Conclusions
6. When Things Go Wrong
6.1. A Process for Debugging Ruby Code
6.2. Capturing the Essence of a Defect
6.3. Scrutinizing Your Code
6.3.1. Utilizing Reflection
6.3.2. Improving inspect Output
6.3.3. Finding Needles in a Haystack
6.4. Working with Logger
6.5. Conclusions
7. Reducing Cultural Barriers
7.1. m17n by Example: A Look at Ruby’s CSV Standard Library
7.2. Portable m17n Through UTF-8 Transcoding
7.2.1. Source Encodings
7.2.2. Working with Files
7.2.3. Transcoding User Input in an Organized Fashion
7.3. m17n in Standalone Scripts
7.3.1. Inferring Encodings from Locale
7.3.2. Customizing Encoding Defaults
7.4. m17n-Safe Low-Level Text Processing
7.5. Localizing Your Code
7.6. Conclusions
8. Skillful Project Maintenance
8.1. Exploring a Well-Organized Ruby Project (Haml)
8.2. Conventions to Know About
8.2.1. What Goes in a README
8.2.2. Laying Out Your Library
8.2.3. Executables
8.2.4. Tests
8.2.5. Examples
8.3. API Documentation via RDoc
8.3.1. Basic Documentation Techniques and Guidelines
8.3.2. Controlling Output with RDoc Directives
8.4. The RubyGems Package Manager
8.4.1. Writing a Gem::Specification
8.4.2. Working with Dependencies
8.5. Rake: Ruby’s Built-in Build Utility
8.6. Conclusions
A. Writing Backward-Compatible Code
A.1. Avoiding a Mess
A.1.1. Selective Backporting
A.1.2. Version-Specific Code Blocks
A.1.3. Compatibility Shims for Common Operations
A.2. Nonportable Features in Ruby 1.9
A.2.1. Pseudo-Keyword Hash Syntax
A.2.2. Multisplat Arguments
A.2.3. Block-Local Variables
A.2.4. Block Arguments
A.2.5. New Proc Syntax
A.2.6. Oniguruma
A.2.7. Most m17n Functionality
A.3. Workarounds for Common Issues
A.3.1. Using Enumerator
A.3.2. String Iterators
A.3.3. Character Operations
A.3.4. Encoding Conversions
A.4. Conclusions
B. Leveraging Ruby’s Standard Library
B.1. Why Do We Need a Standard Library?
B.2. Pretty-Printer for Ruby Objects (pp)
B.3. Working with HTTP and FTP (open-uri)
B.4. Working with Dates and Times (date)
B.5. Lexical Parsing with Regular Expressions (strscan)
B.6. Cryptographic Hash Functions (digest)
B.7. Mathematical Ruby Scripts (mathn)
B.8. Working with Tabular Data (csv)
B.9. Transactional Filesystem-Based Data Storage (pstore)
B.10. Human-Readable Data Serialization (json)
B.11. Embedded Ruby for Code Generation (erb)
B.12. Conclusions
C. Ruby Worst Practices
C.1. Not-So-Intelligent Design
C.1.1. Class Variables Considered Harmful
C.1.2. Hardcoding Yourself Into a Corner
C.1.3. When Inheritance Becomes Restrictive
C.2. The Downside of Cleverness
C.2.1. The Evils of eval( )
C.2.2. Blind Rescue Missions
C.2.3. Doing method_missing Wrong
C.3. Conclusions
Index
n
Next Page
p
Previos Page
h
Book Home
u
Go Up One Level
?
Press ? for Help
esc
Hide Help
Your Ad Here