"hands off! best practices for code hand offs"
DESCRIPTION
BTRANSCRIPT
![Page 1: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/1.jpg)
Best Practices for Code Handoffs
Naomi DushayndushayStanford University LibrariesCode4Lib 2013
HANDS OFF!
![Page 2: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/2.jpg)
Code Handoffs Aren’t Like This
![Page 3: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/3.jpg)
Code Handoffs
![Page 4: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/4.jpg)
Code Handoffs
![Page 5: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/5.jpg)
Code Handoffs
![Page 6: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/6.jpg)
http://www.flickr.com/photos/christinawelsh/3513582560/
I’m supposed
to take over
WHAT???
![Page 7: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/7.jpg)
SourcesClean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008
Refactoring: Improving the Design of Existing Code – Martin Fowler, …, Addison-Wesley Professional, 1999
![Page 8: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/8.jpg)
“The ratio of time spent
reading vs. writing is well over
10:1” – Clean Code
Reading Writing
![Page 9: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/9.jpg)
The Truck Test“What if I were run over by a truck?”
Kittens
![Page 10: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/10.jpg)
Write code as if a stranger will need to understand it.
![Page 11: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/11.jpg)
My code doesn’t have to age long
for me to be a stranger.
![Page 12: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/12.jpg)
The Boy Scout Rule
“Leave the code cleaner than you found it”
paraphrased from Clean Code
![Page 13: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/13.jpg)
“The code needs to be kept clean over time”
- Clean Code
![Page 14: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/14.jpg)
It’s More Than Code• Servers• Configurations• …
![Page 15: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/15.jpg)
ServersConsider Naming By Purpose
- bacon-dev: development- bacon-test: testing- bacon-prod: production
![Page 16: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/16.jpg)
Config Files1. Inline documentation on what
config file expects1. purpose/use of value2. syntax expected (examples!)
2. Try to group settings likely to vary 1. e.g. server name, web service url,
…
![Page 17: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/17.jpg)
# Settings for BnF Images# You will want to copy this file and change the following settings:# 1. coll_fld_val# 2. log_name# 3. default_set (in OAI harvesting params section)# 4. blacklist or whitelist if you are using them
# the value of the "collection" field in the Solr document # (a way to query this OAI harvest only); default is the default_setcoll_fld_val: bnf_images1
# log_dir: directory for log file # (default is logs, relative to harvestdor gem path)log_dir: logs …
![Page 18: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/18.jpg)
production config files should not point to boxes named "dev" or "test”
![Page 19: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/19.jpg)
It’s More Than Code• …• Tools Chosen–Deployment– Automated Monitoring– Issue Tracking– User Feedback
• …
![Page 20: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/20.jpg)
It’s the Tools You Choose“I’m probably not the first person to …”
- … Parse XML- … work with jpeg2000- … Write deployment scripts- … Parse MARC
![Page 21: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/21.jpg)
When NOT to Roll Your Own
- Is there already local expertise?
- What solutions have your colleagues adopted?
- Are there existing tools for this work in this context?
- Which solutions are widely adopted?
- Which solutions are under active development?
![Page 22: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/22.jpg)
It’s More Than Code• …• Scripts• …
![Page 23: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/23.jpg)
Scripts• Named Well– “harvest_set” vs. “get”
• Begin With Comments Explaining Purpose, Arguments Expected, Results
![Page 24: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/24.jpg)
#! /bin/bash # pullThenIndexSirsiIncr.sh# Pull over the latest incremental update files from Sirsi, then# Remove deleted records (per file of ids) from index and update index (with marc records in file)## updated for Naomi's FORK of solrmarc 2011-01-23# Naomi Dushay 2010-04-09…
![Page 25: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/25.jpg)
It’s More Than Code• …• Documentation• …
![Page 26: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/26.jpg)
Documentation isn’t cheating.
![Page 27: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/27.jpg)
Comments and Other Documentation
• Inform• Explain• Clarify• Warn• Need Maintenance!
Use a comment to explain non-obvious, or tricky, or warnings
![Page 28: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/28.jpg)
README• What is this?• How do I install it?• How do I get it running?• How do I use it?– Examples for most common cases
• How do I deploy it?• Where should I look for more
info?
![Page 29: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/29.jpg)
To set up:1. create a yml config file for your collection going to a Solr index. See config/bnf-images.yml for an example.You will want to copy that file and change the following settings:1. coll_fld_val2. log_name3. default_set4. blacklist or whitelist if you are using them…To run:./bin/indexer config/(your coll).yml
![Page 30: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/30.jpg)
It’s More Than Code• …• TESTS • …
![Page 31: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/31.jpg)
Tests Should• demonstrate how code should
work• be fast• contain their test data (or have
it in the test file, as close to test code as is practical)
• …• be viewed as code: readable,
maintained …
![Page 32: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/32.jpg)
Tests Should• …• be viewed as code: readable,
maintained …
![Page 33: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/33.jpg)
It’s More Than Code• …• Continuous Integration• …
![Page 34: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/34.jpg)
Continuous Integration• Builds Should– Run tests– Run test coverage– Be triggered by new code
• Failures Should– Be addressed ASAP
![Page 35: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/35.jpg)
KISSK eepI tS impleS tupid
http://www.flickr.com/photos/alexdram/3368983298/
![Page 36: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/36.jpg)
DRYD on’tR epeatY ourself
http://www.flickr.com/photos/deeanna/20357091/
![Page 37: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/37.jpg)
Readable Code• Follow Conventions• Meaningful Names– Variable–Method– Class– File
• Small, single purpose methods
![Page 38: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/38.jpg)
Cleverness that reduces readability isn’t clever.
![Page 39: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/39.jpg)
SourcesClean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008
Refactoring: Improving the Design of Existing Code – Martin Fowler, …, Addison-Wesley Professional, 1999
![Page 40: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/40.jpg)
Errors and Corner Cases• Exceptions, not Error Codes• Test exception expectations
it "should log a warning when it finds direct non-whitespace text content" do x = stuff @logger.should_receive(:warn).with("Found direct text content: 'mistake' in page geeby-deeby") @rsolr_client.should_receive(:add) @parser.parse(x) end
![Page 41: "Hands Off! Best Practices for Code Hand Offs"](https://reader031.vdocument.in/reader031/viewer/2022013003/5470314baf7959a60e8b45af/html5/thumbnails/41.jpg)
Thank You!