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
2. Antikythera Mechanism
3. It’s Been Stolen!
4. Why do we want it?
5. http://abstrusegoose.com/432
6. 40-80% of a project is maintenance
7. Maintenance is good!
8. Our job is to read code, Not to write it
11. Where do we start?
12. README.md
16. Talk to people
17. Inventory the code
18. Dependencies
19. Build the project
20. Accept you're missing 10%
21. What is dangerous?
22. What should be saved?
23. Who created this?
24. Reconnaissance Time
26. I'm sorry, Dave. I'm afraid I can't do that
27. $ grep -lr "sorry, Dave" * src/HAL/Security/DoorPasswordValidator.php
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; } }
29. We’re in!
30. Navigation
31. Read the code
33. Don’t trust the comments
34. namespace Casino\Game; class Roulette { /** * Returns a random number */ private function alwaysReturnSix(){ } }
35. namespace Casino\Game; class Roulette { /** * Returns a random number */ private function alwaysReturnSix(){ return 4; } }
36. Don’t trust the code
37. Look for side effects
38. public function triggerFireAlarm() { $this->startSprinklers(); $this->callFireBrigade(); $this->releaseDoorLocks(); }
39. Double Check Your Understanding
40. Names are important
41. Find Patterns
42. Prove you understand it
43. I don’t understand it
44. Debugging
45. use everything
46. Everything goes
47. DDD
48. Die Driven Debugging
49. Does this code even run?
50. /** * Returns a random number */ private function alwaysReturnSix() { die('Yes it does'); return 4; }
51. echo '######################'.PHP_EOL; echo count($vistorsInLastDay); echo '######################'.PHP_EOL;
52. if (count($visitorsInLastDay) > 5){ var_dump(visitorsInLastDay);die; }
53. echo '######################'.PHP_EOL; var_dump(debug_backtrace()); echo '######################'.PHP_EOL;
54. class MyVerifier extends SomethingVerifier { public function userIsAdmin($user) { return true; } }
55. XDebug
56. XDebug.scream
57. XDebug_break();
58. if (count($visitorsInLastDay) > 5){ xdebug_break(); }
59. XHPROF
60. DDD +XDebug + XHProf == WINNING
61. Observer Effect
62. I’m feeling better
63. But I’m still noT 100%
64. Project History
65. git log -S <search>
66. git log -S antikythera
67. commit 5288d5804a3fc20dae4f3b2deeaa7f687595aff1 Author: Rasmus Lerdorf <rasmus@example.com> 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
68. What’s changed recently?
69. What changes together?
70. Explicit
71. commit 0dc164fb052f4b838a674648aa29d83b60f01fa2 Author: Rasmus Lerdorf <rasmus@example.com> 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
72. Implicit
73. commit 2915dabebc8b87b84ec40fac0f4954fb84f3b7cd Author: Rasmus Lerdorf <rasmus@example.com> 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
74. Common Causes
75. Code Maat
76. statistic,value number-of-commits,2254 number-of-entities,3179 number-of-entities-changed,9979 number-of-authors,106
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
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
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
80. entity,coupled,degree,average-revs application/config/config.php,application/config/database.php,90,6
81. Visualisations Help
82. symfony/symfony
83. rails/rails
84. symfony/symfony
85. rails/rails
86. Code Ownership
87. Author Coupling
88. Code Ownership
89. Code Ownership
90. Commit Msg
91. Commit Msg
92. Commit times
93. Commit History
94. github/adamtornhill/code-maat Codescene.io codehistoryminer.com github/smontanari/code-forensics
95. History Analysis is flawed
96. Leaving a legacy
97. Secure the site
98. Glossary
99. Logging
100. Name things well
101. Build a knowledge map
102. Leave useful comments
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
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