You should be able to break down a front end project by documenting of all the pages and then components they depend on. Then document their flow (which pages link to which and what dialogs / components they open). Then you need to look at how data is managed among all the pages and components. Do they use something like redux for data management? Then how is the business logic is composed and how backend API's are used. Also for a front end project how are styles managed through out the application.
Ask HN: Working with large code base for the first time
11–20 of 90 posts
Re: Ask HN: Working with large code base for the first time
#12Usually large codebases have to follow the best practice of the framework they use. If you already fluent in that framework, you can jump right in.
Re: Ask HN: Working with large code base for the first time
#13From the root of the repo:
grep -HIron 'your search pattern' *
Re: Ask HN: Working with large code base for the first time
#14These are not rote advice, it’s literally the parts that have been successful as I’ve inherited maintainership of several large projects.
If it’s not already TypeScript, add a tsconfig.json, with allowJs: true, checkJs: true. You’ll probably need some tweaks from there. But merely adding the config is enough to kick VSCode or other language service providers into finding references and a lot more.
Apart from that:
- Keep notes as you uncover how things flow and interact.
- The best way to keep those notes is as part of your project’s documentation. Use JSDoc and TypeScript declaration files. Learn how these docs interact and aid navigation.
- @see is a particularly useful JSDOC tag!
- Speed up the build if it’s slow. No really, it’s going to help with discoverability in the codebase! Breaking flow to wait for a build is a sure way to lose track of your journey.
- Backfill tests before you touch implementation. Even if you suspect the tests might be redundant. Odds are they’re not, but even if they are, (1) that’s more documentation you can reference and (2) any other maintainers/contributors seeing redundancy can use that as a signal to shortcut your familiarization.
- Git blame is your friend. Some days it’s your best friend.
- Look in weird places! Sometimes that old version of a dependency is pinned for a reason. Sometimes it’s pinned to a fork, again for a reason.
Re: Ask HN: Working with large code base for the first time
#15Logging to console, to build a mental model of the codepaths data and events take.
Git grep (or ripgrep) to find usage - useful when refactoring and to see how data is used/accessed and where it's passed around. Also useful to note where certain data doesn't show up: you can infer some structure from this.
Looking at when something was last changed with git blame can be useful. Is something suddenly broken, but hasn't been changed in 5 years? Could give an indication of where not to look on a first pass.
Break some things (locally) on purpose. Get a feel for how errors bubble up through the application and how dependant code behaves when something is wrong.
Look over the last handful of PRs/merged patches. It can be helpful to see these smaller pieces of code, the changeset, and their associated context - whether it was a feature, a bugfix, and what the code was supposed to achieve.
Use existing code in the codebase as a styleguide. Most work on large codebases isn't groundbreaking or innovative, so you're likely to find existing code similar to what you're currently trying to achieve that you can use to guide you.
If possible, make use of code reviews with colleagues.
Re: Ask HN: Working with large code base for the first time
#16- Search for unique-looking strings from whatever view you're trying to modify to find the associated html/js file.
- Pull up the commit history for the file to see what other files were modified along with it the last few times. This will give you dependencies and linkages.
- Make your change and then ask your ide/command line to find all typing/lint errors in your project which will help you find other dependencies you may have missed.
- If you get stuck, reach out to the authors or reviewers of previous PRs. (Hint: you may want to include them as reviewers. They'll give good feedback and you'll engender good will by keeping them in the loop when you touch their corner of the codebase)
- Write a few solid unit tests. Maybe even clean up the testing code a little bit while you're there.
- Write a concise but informative description of your changes in your PR. If you made two or more logical changes, split your PR and stack them. Your teammates will appreciate the shorter PRs and you will get feedback more quickly.
- Land the PR in a timely manner and keep an eye on it until it hits prod.
- Once in prod, test it yourself and keep an eye on the logs for a day or three.
- Bonus: put all changes behind feature flags to do slow rollouts and so you can quickly revert without waiting for a deploy. Make a task to remind yourself to remove the dead code behind the flag in month or so when you're pretty sure it's stable.
Re: Ask HN: Working with large code base for the first time
#17If it's C, cflow (example usage: cflow .c .h) and doxygen (needs some config, but there's a GUI) could come in handy. Doxygen is capable of generating call graphs if you install some external dependencies.
If it's a different language, you could try looking around in the docs if anyone's generated callgraphs, or you could look up ways to do so.
To trace the code you could use a debugger -- e.g. if it's gdb just issue the command 'start' and then step through from the main function to see how things go. Or (assuming it's something like a C program) you could get an strace (example usage: strace -vvvttf -o strace.log ./program) and maybe get a feeling for the config/etc. files read or written to, network services accessed, etc.
It would help if you could tell us what kind of program it is, or what kind of programming language it's written in.
Re: Ask HN: Working with large code base for the first time
#18Assuming sourcemap pipelines work, open your browser and put debuggers on anything you don't understand tracing requests / invocations. Start with something conceptual like a particular page / component and work your way out beginning at the request entrypoint. Along the way you will likely figure out things like authentication management, routing, view hierarchy and design patterns leveraged, etc. Allow a particular issue you need to resolve guide you if needed, but don't sweat the learning curve, as it is required and should be expected.
Re: Ask HN: Working with large code base for the first time
#19You should be able to break down a front end project by documenting of all the pages and then components they depend on. Then document their flow (which pages link to which and what dialogs / components they open). Then you need to look at how data is managed among all the pages and components. Do they use something like redux for data management? Then how is the business logic is composed and how backend API's are u…
This sounds like some very good suggestions.
Re: Ask HN: Working with large code base for the first time
#20Find out how to run unit tests in your project and then find interesting unit tests to run. Set break points preferably at some launch points of your code and debug through unit tests. The process will take you through relevant parts of the code, the decisions being made etc.
This method has also worked for me when building features in a large codebase. Write a unit test first and then keep checking where the code breaks and fix those until your test succeeds. This is effectively TDD. Note that you might have to refactor the code for better design but it gets you started towards understanding the flow.