Hands off! Best Practices and Top Ten Lists for Code Handoffs
- Naomi Dushay, Stanford University Library
Code handoffs are never smooth. Ever.
Ratio of time spend reading vs. writing code, 10:1.
The Truck Test
- what if you were run over a truck and someone else had to take over?
- need to code so a stranger can read it and understand it
The Boy Scout Rule
- “Leave the code cleaner than you found it”
- need to maintain your code
- otherwise you’re part of the problem
It’s More Than Code
- naming should make sense: servers, scripts, everything
- config files should not point to boxes
- tools chosen can be the problem
- should you be rolling this on your own?
- probably something been done before
- some think if you write code really well, then you don’t need to comment. Not true.
- Documentation and comments are there to inform, explain, clarify, warn, need maintenance
- readme’s should make sense
- tests are code, should also think about readability of these
- failures should be addressed ASAP
- KISS – Keep It Simple Stupid
- DRY – don’t repeat yourself
Readable Code
- follow conventions
- meaningful names: variable, method, class, file
- small, single purpose methods
Cleverness that reduces readability isn’t clever.
Sources
- Clean Code: A Handbook of Agile Software Craftsmanship by Robert Martin
- Refactoring: Improving the Design of Existing Code by Martin Folwer et al.
The Care and Feeding of a Crowd
- Shawn Averkamp, University of Iowa
- Matthew Butler, University of Iowa
DIY History
- transcribe items in collection
- omeka + scripto + mediawiki
- still in development: want to add social media aspects/integration
- err sorry, brain temporarily sort of died. See slides and I’ll go get a cookie to recharge
How to be an effective evangelist for your open source project Creating a Commons
- Bess Sadler, Stanford University Library
Lost a member of our community this year: Aaron Swartz
- helped to define Creative Commons licenses
- 3 versions: machine, human, and lawyer readable
- code4lib should do the same principle
- shared engineering practices are becoming more and more important
- investment that’s worth it
- please get code contributors to sign a contributor license agreement
- can determine whether contract allows participation
- don’t want to lose informal sharing, but law cases have happened and we need to protect ourselves
Building Code
- what are we building?
- we are building a culture, a commons
- Fedora4lib – came early and rented a house together
- Hydra = a community
- cultivate a place where we can
- teaching at Ruby on Rails workshops – too big a job to leave to a small group of people
Hacker Epistemology
- how is knowledge acquired?
- how do we decide what’s true?
- collaboration with disregard of conventional mental thinking
Building the Community
- need to expand and include everyone who wants to join
- more steps in building a more inclusive community
- adopted a code of conduct, because it was a good idea and making an explicit statement
- need to let other people to know that we’re trying
- “We are all imposters.” – just acknowledge it, we all feel that way, but bolster ourselves
- allow ourselves to be seen even when there’s no guarantee of success
- we can support each other
- cannot be accomplished alone
- want to craft a process for submitting issues
Thank you, code4lib!
The End
And that’s it! Until 2014.
