Code Archaeology: Becoming Indiana Jones

Code archaeology is one of the most important skills you will ever learn as a developer. How many times have you been thrown into legacy projects with no environment setup, no documentation, and little support from coworkers? The ability to hit the ground running on new applications is a sought-after skill for many employers. In this talk, we will take an open-source project that we have never seen before and work through the steps required to get it up and running so we can start contributing today.

Transcript

1. and the
   Evil Architects
   @mheap at #tek16
   

   View Slide

2. Antikythera Mechanism
   

   View Slide

3. It’s Been Stolen!
   

   View Slide

4. Why do we want it?
   

   View Slide

5. 40-80% of a project
   is maintenance
   

   View Slide

6. Why so much?
   

   View Slide

7. Our job is to read
   code, Not to write it
   

   View Slide

8. *flying noises*
   

   View Slide

9. Where do
   we start?
   

   View Slide

10. What should be saved?
    

    View Slide

11. What is dangerous?
    

    View Slide

12. Who created this?
    

    View Slide

13. README.md
    

    View Slide

14. Talk to people
    

    View Slide

15. Inventory the code
    

    View Slide

16. Dependencies
    

    View Slide

17. Build the project
    

    View Slide

18. Accept you're
    missing 10%
    

    View Slide

19. Time to go in!
    

    View Slide

20. Security!
    

    View Slide

21. “Incorrect Password”
    

    View Slide

22. $ grep -lr "Incorrect password" *
    src/Architect/Security/DoorPasswordValidator.php
    

    View Slide

23. namespace Architect\Security;
    class DoorPasswordValidator {
    private $doorPassword = 'shibboleet';
    public function validate($input) {
    if ($this->doorPassword !== $input) {
    throw new \Exception("Incorrect password");
    }
    return true;
    }
    }
    

    View Slide

24. We’re in!
    

    View Slide

25. Navigation
    

    View Slide

26. Draw a map
    

    View Slide

27. View Slide

28. Read the code
    

    View Slide

29. Don’t trust the
    comments
    

    View Slide

30. namespace Architect\Game;
    class Roulette {
    /**
    * Returns a random number
    */
    }
    

    View Slide

31. Don’t trust
    the code
    

    View Slide

32. namespace Architect\Game;
    class Roulette {
    /**
    * Returns a random number
    */
    private function spinRandom(){
    return 4;
    }
    }
    

    View Slide

33. Does this code
    even run?
    

    View Slide

34. /**
    * Returns a random number
    */
    private function spinRandom() {
    die('Yes it does');
    return 4;
    }
    

    View Slide

35. Look for
    side effects
    

    View Slide

36. public function triggerFireAlarm() {
    $this->startSprinklers();
    $this->callFireBrigade();
    $this->releaseDoorLocks();
    }
    

    View Slide

37. Naming Things
    

    View Slide

38. Find intentions
    

    View Slide

39. Find Patterns
    

    View Slide

40. Prove you
    understand it
    

    View Slide

41. I don’t
    understand it
    

    View Slide

42. Debugging
    

    View Slide

43. use everything
    

    View Slide

44. Everything goes
    

    View Slide

45. DDD
    

    View Slide

46. Die Driven Debugging
    

    View Slide

47. echo '######################'.PHP_EOL;
    echo $currentCasinoCapacity;
    echo '######################'.PHP_EOL;
    

    View Slide

48. if (!isset($visitors['derick_rethans'])){
    var_dump($visitors);die;
    }
    

    View Slide

49. echo '######################'.PHP_EOL;
    var_dump(debug_backtrace());
    echo '######################'.PHP_EOL;
    

    View Slide

50. class MyDoorMan extends DoorMan {
    public function changeShiftAt($val) {
    throw new Exception("Changing at $val");
    }
    }
    

    View Slide

51. XDebug
    

    View Slide

52. XDebug.scream
    

    View Slide

53. XDebug_break();
    

    View Slide

54. if (!isset($visitors['derick_rethans'])){
    xdebug_break();
    }
    

    View Slide

55. xdebug_debug_zval();
    

    View Slide

56. $michael = new Person(‘Michael’);
    $bouncer =& $michael;
    $dealer =& $michael->hands;
    xdebug_debug_zval(
    'michael'
    );
    // Outputs
    michael: (refcount=2, is_ref=1)=array (
    0 => (refcount=1, is_ref=0)=1,
    1 => (refcount=1, is_ref=0)=2,
    2 => (refcount=2, is_ref=1)=3)
    

    View Slide

57. XHPROF
    

    View Slide

58. DDD +X Debug
    + XHProf == WINNING
    

    View Slide

59. Observer Effect
    

    View Slide

60. I’m feeling better
    

    View Slide

61. Project History
    

    View Slide

62. git log -S
    

    View Slide

63. git log -S antikythera
    

    View Slide

64. commit 5288d5804a3fc20dae4f3b2deeaa7f687595aff1
    Author: Eli White
    Date: Tue May 24 09:33:59 2016 +0000
    Add new secure storage facility. (Closes #42)
    The existing storage facilities use symmetrical encryption keys which allow anyone with
    the password to access them. The new storage is more secure and requires both a password and
    my handprint.
    There’s nothing in there yet but we’ll put the Antikythera in it as soon as it arrives
    

    View Slide

65. What’s changed
    recently?
    

    View Slide

66. Temporal Coupling
    

    View Slide

67. Explicit
    

    View Slide

68. commit 0dc164fb052f4b838a674648aa29d83b60f01fa2
    Author: Oscar Merida
    Date: Fri May 20 12:14:55 2016 +0000
    Changed from European to American roulette table. Gives the house a better edge
    5 2 src/Architect/Game/Roulette.php
    14 0 test/Architect/Game/RouletteTest.php
    

    View Slide

69. Implicit
    

    View Slide

70. commit 2915dabebc8b87b84ec40fac0f4954fb84f3b7cd
    Author: Eli White
    Date: Sun May 22 21:27:31 2016 +0000
    Removed the corner roulette table as it was crooked. Updated Fire plan to remove table
    0 2 src/Architect/FloorPlan.php
    0 1 src/Architect/Policy/FireEscape.php
    

    View Slide

71. Common Causes
    

    View Slide

72. Code Maat
    

    View Slide

73. statistic,value
    number-of-commits,2254
    number-of-entities,3179
    number-of-entities-changed,9979
    number-of-authors,106
    

    View Slide

74. entity,n-authors,n-revs
    src/Room/VipLounge.php,26,181
    src/Game/Blackjack.php,22,76
    src/Controller/CloakroomController.php,21,110
    src/People/FloorManager.php,19,91
    

    View Slide

75. entity,age-months
    src/Security/PasswordManager.php,1
    src/Bar/DrinkPrices.php,1
    src/Game/Poker/Stud.php,3
    src/Security/RadioChannels.php,7
    

    View Slide

76. entity,coupled,degree,average-revs
    src/Manager/FloorManager.php,src/Factory/TableFactory.php,100,19
    src/Vendor/Drinks.php,src/Vendor/Snacks.php,60,10
    src/Room/VipLounge.php,src/Room/Cloakroom,14,172
    

    View Slide

77. entity,coupled,degree,average-revs
    application/config/config.php,application/config/database.php,90,6
    

    View Slide

78. History Analysis
    is flawed
    

    View Slide

79. Leaving a legacy
    

    View Slide

80. Secure the site
    

    View Slide

81. Rosetta Stone
    

    View Slide

82. Logging
    

    View Slide

83. Name things well
    

    View Slide

84. Build a knowledge map
    

    View Slide

85. Leave useful comments
    

    View Slide

86. //
    // Dear maintainer:
    //
    // Once you are done trying to 'optimize' this routine,
    // and have realized what a terrible mistake that was,
    // please increment the following counter as a warning
    // to the next guy:
    //
    // total_hours_wasted_here = 42
    //
    I’ve been @mheap, you’ve been awesome!
    https://joind.in/17041
    

    View Slide