667
edits
Changes
no edit summary
* [[DPS909 & OSD600 Winter 2017 - Lab 4 | Lab 4]]
==Week 5==
* Strategies for Understanding Code
** '''RTFM''' (Read the F.....antastic Manual!): <code>README.md</code>, <code>Contributing.md</code>, website?, wiki? Read it. Twice. Mostly you want to start building up a list of keywords, common themes, and useful tips you can use later when you start trying things.
** '''Bottom-Up''': look at the code, directory structure, scan for file/dir names that related to your task. Don't get bogged down, just go for a walk in the code and take note of what you see.
** '''Top-Down''': try to find a UI string (e.g., menu name, button label) that you can search for within the code
** '''Sideways Excavation''': look at a similar code path or feature for clues about where you should work (e.g., want to add a new menu option to 'File', look at one of the existing ones)
** '''Time Machine''': use project history (commits, log messages, blame, issues) for info about how code was introduced and evolved
** '''Clean Room''': read the <code>test/</code> code. What do the original devs ''think'' the code should do? How do they use it, when do they use, in what order to they call things, which code is related, etc.
** '''Family Tree''': find code in other projects/repos that uses the same code you're interested in. How does Project X use this API in their code? Use other people's code to build an understanding of what you should do (e.g., read extension code from https://brackets-registry.aboutweb.com/ to understand Brackets APIs)
** '''Ask an Elder''': don't be afraid to ask for clarification from more experienced devs. Often they can narrow your search to a particular area of the code. Use mailing lists, ask in bugs/issues, discuss on chat systems, talk to people IRL!
** '''Just Try Stuff''': often the best thing to do is simply to try things. Create a new branch <code>experiments</code> and start adding logging, debug statements, delete things and see what happens, add things and see what happens, change things and see what happens! If you can break it, you can probably make it do something useful.
* Tools for Understanding Code:
** <code>git grep</code>
** <code>git blame</code>
** Search within commit messages: <code>git log --grep "some string"</code>
** Search within the commit content for addition/removal of a string: <code>git log -S "some string"</code>
** Search all branches: <code>git log -S 'populate_database' --all</code>
** Search in date range: <code>git log -p --since=2012-01-01 --until=2015-02-01</code>
** Log Formatting examples
*** <code>git log --graph --pretty=oneline --decorate</code>
*** <code>git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short</code>
*** <code>git log --graph --pretty=format:'%Cred%h%Creset %an: %s - %Creset %C(yellow)%d%Creset %Cgreen(%cr)%Creset' --abbrev-commit --date=relative</code>
** Searching on GitHub: Repositories, Code, Commits, Issues, Wikis
*** Find all uses of <code>fadeIn()</code>https://github.com/search?utf8=%E2%9C%93&q=fadeIn%28%29&type=Repositories&ref=searchresults
*** Within repo vs. all of GitHub (e.g., how a function is used, finding similar bugs based on error messages, who is using a piece of code, etc)
*** Searching within repo only works in original repo vs. forks (e.g., https://github.com/adobe/brackets not https://github.com/mozilla/brackets)
*** Commits, Code (and Languages), Issues
<!--
