Code handover techniques - hand over a mental model, not just code

This resource first appeared in issue #27 on 05 Jun 2020 and has tags Technical Leadership: Software Development, Managing A Team: Knowledge Sharing

7 practices you should follow for a successful code handover - Nicolas Carlo
Programming as Theory Building - Diogo Felix

These are interesting articles to read back to back.

Nicholas Carlo has his usual pragmatic information about legacy code - in this case, avoiding code becoming legacy code by executing a handoff between an outgoing developer and a new one. The key ones, I think, are:

• New dev writes the docs, reviewed by old dev
• Keep old dev engaged
• Jointly write more tests to share understanding of the system
• Try to jointly predict where fixes/improvements should be made
• Don’t refactor code without a specific goal

The post by Diogo Felix is more theoretical/philisophical, based on a 1985 essay of the same name by Peter Naur. The argument is that programming creates code, of course, but that’s only one output, an incomplete representation of what was in the developer’s head. (Evidence: try revisiting someone else’s code.) The work of programming is theory-building (I think we’d say model building now). The developer(s) built a mental model of the problem and its solution.

Code becomes legacy, then, when the code is all that’s left. So its vital to transfer over the mental model as well as the code base when developers are leaving.