best practices for code handoffs · clean code: a handbook of agile software craftsmanship –...
TRANSCRIPT
![Page 1: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/1.jpg)
Best Practices for Code Handoffs
Naomi Dushay ndushay Stanford University Libraries Code4Lib 2013
HANDS OFF!
![Page 2: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/2.jpg)
Code Handoffs Aren’t Like This
![Page 3: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/3.jpg)
Code Handoffs
![Page 4: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/4.jpg)
Code Handoffs
![Page 5: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/5.jpg)
Code Handoffs
![Page 6: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/6.jpg)
h4p://www.flickr.com/photos/chris=nawelsh/3513582560/
I’m supposed to take over
WHAT???
![Page 7: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/7.jpg)
Sources
Clean 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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/8.jpg)
“The ra=o of =me spent
reading vs. wri-ng is well over
10:1” – Clean Code
Reading Wri=ng
![Page 9: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/9.jpg)
The Truck Test
“What if I were run over by a truck?”
![Page 10: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/10.jpg)
Write code as if a stranger will need to understand it.
![Page 11: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/11.jpg)
My code doesn’t have to age long for me to be a stranger.
![Page 12: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/12.jpg)
The Boy Scout Rule
“Leave the code cleaner than you found it” paraphrased from Clean Code
![Page 13: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/13.jpg)
“The code needs to be kept clean over time” - Clean Code
![Page 14: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/14.jpg)
It’s More Than Code
• Servers • Configurations • …
![Page 15: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/15.jpg)
Servers
Consider Naming By Purpose - bacon-dev: development - bacon-test: testing - bacon-prod: production
![Page 16: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/16.jpg)
Config Files
1. Inline documentation on what config file expects 1. purpose/use of value 2. syntax expected (examples!)
2. Try to group settings likely to vary 1. e.g. server name, web service url, …
![Page 17: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/17.jpg)
# Se3ngs for BnF Images # You will want to copy this file and change the following se3ngs: # 1. coll_fld_val # 2. log_name # 3. default_set (in OAI harves-ng params sec-on) # 4. blacklist or whitelist if you are using them # the value of the "collec-on" field in the Solr document # (a way to query this OAI harvest only); default is the default_set coll_fld_val: bnf_images1 # log_dir: directory for log file # (default is logs, rela-ve to harvestdor gem path) log_dir: logs …
![Page 18: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/18.jpg)
production config files should not point to boxes named "dev" or "test”
![Page 19: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/19.jpg)
It’s More Than Code
• … • Tools Chosen – Deployment – Automated Monitoring – Issue Tracking – User Feedback
• …
![Page 20: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/22.jpg)
It’s More Than Code
• … • Scripts • …
![Page 23: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/23.jpg)
Scripts
• Named Well – “harvest_set” vs. “get”
• Begin With Comments Explaining Purpose, Arguments Expected, Results
![Page 24: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/25.jpg)
It’s More Than Code
• … • Documentation • …
![Page 26: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/26.jpg)
Documentation isn’t cheating.
![Page 27: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/29.jpg)
To set up: 1. create a yml config file for your collec-on going to a Solr index. See config/bnf-‐images.yml for an example. You will want to copy that file and change the following se3ngs: 1. coll_fld_val 2. log_name 3. default_set 4. blacklist or whitelist if you are using them … To run: ./bin/indexer config/(your coll).yml
![Page 30: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/30.jpg)
It’s More Than Code
• … • TESTS • …
![Page 31: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/32.jpg)
Tests Should
• … • be viewed as code: readable,
maintained …
![Page 33: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/33.jpg)
It’s More Than Code
• … • Continuous Integration • …
![Page 34: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/35.jpg)
KISS
K eep I t S imple S tupid
h4p://www.flickr.com/photos/alexdram/3368983298/
![Page 36: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/36.jpg)
DRY
D on’t R epeat Y ourself
h4p://www.flickr.com/photos/deeanna/20357091/
![Page 37: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/37.jpg)
Readable Code
• Follow Conventions • Meaningful Names – Variable – Method – Class – File
• Small, single purpose methods
![Page 38: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/38.jpg)
Cleverness that reduces readability isn’t clever.
![Page 39: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/39.jpg)
Sources
Clean 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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/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: Best Practices for Code Handoffs · Clean Code: A Handbook of Agile Software Craftsmanship – Robert Martin, Prentice Hall, 2008 Refactoring: Improving the Design of Existing Code](https://reader036.vdocument.in/reader036/viewer/2022071213/604043282b4474565725fa88/html5/thumbnails/41.jpg)
Thank You!