Code Archaeology: Becoming Indiana Jones

Code archaeology is one of the most important skills you’ll ever learn as a developer. How many times have you been thrown into projects with no environment setup, no documentation, and very little support from coworkers? Being able to quickly work out how an application is structured so that you can start making changes is a sought after skill for many employers.

In this talk, we’ll take an open source project that we’ve never seen before and work through the steps required to get it up and running so that we can start working on features. Once you know the steps, they can be applied to any project in any language to get you contributing in no time.

Transcript

1. and the
   Antikythera Mechanism
   @mheap at #phpbnl17
   

   View Slide

2. Antikythera Mechanism
   

   View Slide

3. It’s Been Stolen!
   

   View Slide

4. Why do we want it?
   

   View Slide

5. http://abstrusegoose.com/432
   

   View Slide

6. 40-80% of a project
   is maintenance
   

   View Slide

7. Maintenance
   is good!
   

   View Slide

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

   View Slide

9. View Slide

10. View Slide

11. Where do
    we start?
    

    View Slide

12. README.md
    

    View Slide

13. View Slide

14. View Slide

15. View Slide

16. Talk to people
    

    View Slide

17. Inventory the code
    

    View Slide

18. Dependencies
    

    View Slide

19. Build the project
    

    View Slide

20. Accept you're
    missing 10%
    

    View Slide

21. What is dangerous?
    

    View Slide

22. What should be saved?
    

    View Slide

23. Who created this?
    

    View Slide

24. Reconnaissance Time
    

    View Slide

25. View Slide

26. I'm sorry, Dave. I'm
    afraid I can't do that
    

    View Slide

27. $ grep -lr "sorry, Dave" *
    src/HAL/Security/DoorPasswordValidator.php
    

    View Slide

28. namespace HAL\Security;
    use HAL\Security\Validator;
    class DoorPasswordValidator extends Validator {
    private $doorPassword = 'beneluxisawesome';
    public function validate($input) {
    if ($this->doorPassword !== $input) {
    throw new \Exception("I'm sorry, Dave. I'm afraid
    I can't do that");
    }
    return true;
    }
    }
    

    View Slide

29. We’re in!
    

    View Slide

30. Navigation
    

    View Slide

31. Read the code
    

    View Slide

32. View Slide

33. Don’t trust the
    comments
    

    View Slide

34. namespace Casino\Game;
    class Roulette {
    /**
    * Returns a random number
    */
    private function alwaysReturnSix(){
    }
    }
    

    View Slide

35. namespace Casino\Game;
    class Roulette {
    /**
    * Returns a random number
    */
    private function alwaysReturnSix(){
    return 4;
    }
    }
    

    View Slide

36. Don’t trust
    the code
    

    View Slide

37. Look for
    side effects
    

    View Slide

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

    View Slide

39. Double Check
    Your Understanding
    

    View Slide

40. Names are
    important
    

    View Slide

41. Find Patterns
    

    View Slide

42. Prove you
    understand it
    

    View Slide

43. I don’t
    understand it
    

    View Slide

44. Debugging
    

    View Slide

45. use everything
    

    View Slide

46. Everything goes
    

    View Slide

47. DDD
    

    View Slide

48. Die Driven Debugging
    

    View Slide

49. Does this code
    even run?
    

    View Slide

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

    View Slide

51. echo '######################'.PHP_EOL;
    echo count($vistorsInLastDay);
    echo '######################'.PHP_EOL;
    

    View Slide

52. if (count($visitorsInLastDay) > 5){
    var_dump(visitorsInLastDay);die;
    }
    

    View Slide

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

    View Slide

54. class MyVerifier extends SomethingVerifier {
    public function userIsAdmin($user) {
    return true;
    }
    }
    

    View Slide

55. XDebug
    

    View Slide

56. XDebug.scream
    

    View Slide

57. XDebug_break();
    

    View Slide

58. if (count($visitorsInLastDay) > 5){
    xdebug_break();
    }
    

    View Slide

59. XHPROF
    

    View Slide

60. DDD +XDebug
    + XHProf == WINNING
    

    View Slide

61. Observer Effect
    

    View Slide

62. I’m feeling better
    

    View Slide

63. But I’m still noT 100%
    

    View Slide

64. Project History
    

    View Slide

65. git log -S
    

    View Slide

66. git log -S antikythera
    

    View Slide

67. commit 5288d5804a3fc20dae4f3b2deeaa7f687595aff1
    Author: Rasmus Lerdorf
    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

68. What’s changed
    recently?
    

    View Slide

69. What changes
    together?
    

    View Slide

70. Explicit
    

    View Slide

71. commit 0dc164fb052f4b838a674648aa29d83b60f01fa2
    Author: Rasmus Lerdorf
    Date: Fri May 20 12:14:55 2016 +0000
    Added HAL to the villa’s security system on both the front and back doors
    5 2 src/Villa/Structure/Door.php
    14 0 test/Villa/Structure/DoorTest.php
    

    View Slide

72. Implicit
    

    View Slide

73. commit 2915dabebc8b87b84ec40fac0f4954fb84f3b7cd
    Author: Rasmus Lerdorf
    Date: Sun May 22 21:27:31 2016 +0000
    Bought a new car. Updated town parking permit to new registration
    12 0 src/Garage/Car/Ferrari.php
    1 1 src/Town/ParkingPermits/Rasmus.php
    

    View Slide

74. Common Causes
    

    View Slide

75. Code Maat
    

    View Slide

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

    View Slide

77. entity,n-authors,n-revs
    src/Room/Library.php,26,181
    src/Casino/Game/Roulette.php,22,76
    src/Controller/HallwayController.php,21,110
    src/People/Cleaner.php,19,91
    

    View Slide

78. entity,age-months
    src/Security/PasswordManager.php,1
    src/People/Cleaner.php,1
    src/Casino/Game/Roulette.php,3
    src/Security/SafeCombination.php,7
    

    View Slide

79. entity,coupled,degree,average-revs
    src/People/Cleaner.php,src/HAL/Security/DoorPasswordValidator.php,100,19
    src/Room/Lounge/Wallpaper.php,src/Room/Bedroom/Wallpaper.php,60,10
    

    View Slide

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

    View Slide

81. Visualisations Help
    

    View Slide

82. symfony/symfony
    

    View Slide

83. rails/rails
    

    View Slide

84. symfony/symfony
    

    View Slide

85. rails/rails
    

    View Slide

86. Code Ownership
    

    View Slide

87. Author Coupling
    

    View Slide

88. Code Ownership
    

    View Slide

89. Code Ownership
    

    View Slide

90. Commit Msg
    

    View Slide

91. Commit Msg
    

    View Slide

92. Commit times
    

    View Slide

93. Commit History
    

    View Slide

94. github/adamtornhill/code-maat
    Codescene.io
    codehistoryminer.com
    github/smontanari/code-forensics
    

    View Slide

95. History Analysis
    is flawed
    

    View Slide

96. Leaving a legacy
    

    View Slide

97. Secure the site
    

    View Slide

98. Glossary
    

    View Slide

99. Logging
    

    View Slide

100. Name things well
     

     View Slide

101. Build a knowledge map
     

     View Slide

102. Leave useful comments
     

     View Slide

103. Attribution
     https://upload.wikimedia.org/wikipedia/commons/f/f5/
     Second_world_war_europe_1943-1945_map_en.png CC-BY-SA
     https://archive.org/details/PET717_Var3 CC-BY
     https://www.flickr.com/photos/132130100@N02/27448816326/ CC-BY-ND
     https://www.flickr.com/photos/rockandrollfreak/10154906473 CC-BY-ND
     https://www.flickr.com/photos/johnwardell/80125882 BY-NC-ND
     

     View Slide

104. //
     // 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/talk/b0184
     

     View Slide