Tag: documentation

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

Presentation Slides

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

Full Write Up by Bess herself

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.