I have just started working with one of the client who have existing nodeJS code which they build in last 3 years.<p>Is there any guiding principle which is beneficial while working with existing code base?
My #1 rule for existing codebases: Just because you wouldn't have done it the way they did doesn't mean they did it wrong.<p>I think it's developer nature to look at a huge pile of code that someone else wrote and immediately think: "This is a pile of crap. I can do better, so the first thing to do is rewrite all of this, my way (which just so happens to be _The Right Way_)."<p>Figure out what you're trying to do, and what is keeping you from doing it. Take an iterative approach to get things done. Realize that after 3 years, they have hopefully fixed a lot of bugs and got to a solution that is somewhat mature and better than you can do in a week.
I have a similiar problem like you, except it's Java and more like 15 years old...<p>What helped? Using a debugger and stepping through the code was useful, it's more a less a REST-API here (build ontop of the system, before it was SOAP, etc.pp) and I've just used some heavily used endpoints and stepped through all the way...<p>Another huge boost in understanding was using flamegraphs (not sure what's hip for nodejs maybe this? <a href="https://github.com/davidmarkclements/0x" rel="nofollow">https://github.com/davidmarkclements/0x</a>)<p>This was really an eye opener because that app also used an external huge Java ECM and there was lot's of AOP magic, reading the flamegraphs and looking at the source was a big boost in understanding.<p>It's also a really useful tool to get visibility for performance problems that are not directly visible in the code.<p>If there are tests, reading them might also be worthwile.<p>And take your time... took me a few months to get a basic understanding how it's working (I'm more sysadmin, not really a dev there), so don't except to grasp everything in one week.<p>Ask your colleagues - maybe were to find documentation or if you don't understand something while reading the source.
It depends. Number one, find out if the codebase is bad or just big. This will take a few months, so I try to keep my mouth shut for a while.<p>If it's really that bad, build a world in a teacup. Try to make one small new area of code that's nice and slowly work existing code into it whenever you get the excuse. It's very unlikely they'll allow you to rewrite or even make substantial changes to existing code. If it was allowed, somebody would have done it.<p>It's also unlikely you'll ever have the codebase migrated completely. In my case, this meant migrating part of the app to a new web framework while keeping the ORM layer relatively the same. Focus on the worst parts. Kinda bad stuff can wait. Expect to write some glue between the worlds on your own time.<p>In your case, IMO Node is a bad plaform for large code bases. My approach would be to introduce TypeScript into a small corner of the app and grow it over time. Even in the existing code, Typescript will type checked the JS and make work/refactoring easier.<p>Once you have typescript up and going, pull in some add-ons to make Node work with async code. The biggest downsides of Node are dynamic typing and callback hell. Typescript + async + heavy linting so this doesn't happen again should put you on a good path unless there's more demons lurking in their stack
You haven't said much about your role here, but let's assume that programming figures prominently. Your immediate problem is that you will be given tasks that involve making changes to a codebase that you don't understand very well. There are many different ways to understand a codebase, and to be effective, you will need to learn some of all of them.<p>Firstly, there is the purpose of the system, which means getting to know what its users want from it and how they use it to achieve that. I put that first, because everything else follows from it, but that does not mean that you have to know all there is to know about that aspect before tackling anything else.<p>You will need to learn about your environment's process: whatever is used for task assignment, scheduling and tracking; version control; building; testing and verification, inspections, test setup and execution; integration and deployment. Of these, you will need to know how to get the source code and test any changes you make, before you can do any programming, and a significant landmark in getting to know the system is when, given nothing but a backup of the source and configuration files, you could resurrect it.<p>The more you know about the architecture, the better - it is the first step in understanding how the system meets (or fails to meet) the users' needs. The architecture often imposes requirements and constraints on how you approach completing a given task.<p>Understanding how everything works at the code level would be a desirable goal, but not one that can be achieved quickly (if at all), so you will have to be guided by what you need to understand in order to do do your assigned tasks.<p>It is also useful to know who knows what among the people you will be working with.
I recommend the book <i>Working Effectively with Legacy Code</i> by Michael Feathers. I've been reading it recently, and I've enjoyed the lessons and advice so far.
Based on my years of experience in working with a millions-of-locs over decades codebase:<p>Be aware of the abstraction fallacy: developers are often guided by this insane notion that they can get <i>rid of</i> accidental complexity by wrapping it away behind an abstraction layer. You can't. It's better to suck up to the complexities of the existing system, and prefer explicit, procedural copy-and-pasting than trying to invent your own abstraction layer on top.<p>The problem with the after-the-fact abstraction layer is that if the original team members are not available, you are likely not in possession of the whole theory of the software. Hence it is not likely you can in the beginning choose the right abstractions.<p>The correct way - if possible - to simplify existing code is to refactor the code itself.<p>The specific anti-pattern you will reach by following the false abstraction strategy is the lasagna architecture:
<a href="https://herbertograca.com/2017/08/03/layered-architecture/" rel="nofollow">https://herbertograca.com/2017/08/03/layered-architecture/</a><p>Two literary works that helped me enormously to grok working with legacy code and programming in particular:<p>* Peter Naur's paper "Programming as theory building" - this was an amazing eye opener to me. It specifically highlights several problems that may arise when working with legacy code when the original developers have left the building.<p>* Michael Feathers: Working Effectively With Legacy Code - not to be read necessarily as a "how to" recipe book, but rather as a collection of philosphies and techniques to utilize when faced with a huge in-production codebase. It can be read as a recipe book if the examples match your situation, but that's not the point.
A large codebase under active development presents a moving target; Even if you knew how something worked last week, that code might have changed twice since then. Detailed knowledge in the solution domain gets outdated fast.<p>To address this issues, I work with something I call a behavioral code analysis. In a behavioral code analysis, you prioritize the code based on its relative importance and the likelihood that you will have to work with it and, hence, needs to understand that part. Behavioral code analysis is based on data from how the organization works with the code, and I use version-control data (e.g. Git) as the primary data source. More specifically, I look to identify <i>hotspots</i>. A hotspot is complicated code that the organization has to work with often. So it's a combination of static properties of the code (complexity, dependencies, abstraction levels, etc) and -- more important -- a temporal dimension like change frequency (how often do you need to modify the code?) and evolutionary trends.<p>I have found that identifying and visualizing hotspots speeds up my on-boarding time significantly as I can focus my learning on the parts of the code that are likely to be central to the solution. In addition, a hotspot visualization provides a mental map that makes it easier to mentally fit the codebase into our head.<p>There are a set of public examples and showcases based on the CodeScene tool here: <a href="https://codescene.io/showcase" rel="nofollow">https://codescene.io/showcase</a><p>I have an article that explains hotspots and behavioral code analysis in more depth here: <a href="https://empear.com/blog/prioritize-technical-debt/" rel="nofollow">https://empear.com/blog/prioritize-technical-debt/</a><p>I also have a book, Software Design X-Rays: Fix Technical Debt with Behavioral Code Analysis, that goes into more details and use cases that you might find useful for working with large codebases: <a href="https://pragprog.com/book/atevol/software-design-x-rays" rel="nofollow">https://pragprog.com/book/atevol/software-design-x-rays</a>
The things I do when starting on a new codebase:<p>1) Ask if there is onboarding documentation, or someone who can give you a high-level overview of the codebase. Typically finding a person with a lot of context on the code is the fastest and most thorough way to understand the responsibilities and layouts of a codebase. Ask if they can draw an ER diagram, it's extremely valuable documentation for any additional developers.<p>2) Read all the documentation possible, especially design documentation. This should hopefully give you some clues as to both function (what) and purpose (why). The discussion around this will also introduce you to the major players in the architecture of the codebase.<p>Note this does not necessarily mean formalized design docs, it could just be searching for any README's or relevant wiki pages. You're just gathering threads at this point, and documentation tends to be a lot more compact and easily digestible than foreign code.<p>3) Look at the models - there will be compact representations of data at some point. This gives good insight into the shared language of the code and can give a lot of clues about how things are done. They also tend to be a lot more human-readable than other pieces of code, so this is a plus.<p>4) Find and skim the largest files. Typically these perform the majority of the work, have the most responsibility, and introduce the most bugs. Knowing roughly where the major players are and what they do makes it a lot easier to read any individual file.<p>5) Run the application, find some small behavior (a single, simple endpoint) and debug it, stepping through the application code so you can see how a particular request flows through the system. This can show you how a lot of different concerns within the code are tied together and also ensures that you're set up for both running and debugging the codebase.<p>At this point you should have a fairly solid understanding of at least the most critical points of the codebase, and also be set up to run and debug it. You should also have at least one or two points of contact to ask questions. This gives you a good framework for figuring out how to modify the codebase moving forward.
Some of my rules for a big legacy code base:<p>- don't plan or do a full rewrite - it'll almost never work<p>- learn and use tools to automate the build system and quality assurance (jenkins, sonarqube, docker, git, etc.)<p>- take the time to improve your skills and the skills of your team (coding dojos, experiments)<p>- write automated tests (unit, integration, acceptance) for existing code where ever possible - write at least unit tests and integration tests for new code<p>- do refactoring and first focus on cross cutting concerns (APIs, translations, caching, logging, database, etc.)<p>- migrate things to well tested isolated APIs (e.g. use REST / Graphql APIs with new endpoints in the frontend and try not to use untested code for these APIs)<p>- don't be too backwards compatible (move fast and break things)<p>Hope it helps ;)
A lot of people are giving advice on changing/testing/refactoring etc, I'm not sure if that's what you are asking, as opposed to how to lean a new code base.<p>My technique for learning code bases, other than asking other devs questions like :-<p>"What architectural patterns are you using?"
"How do you deal with testing?"
"How is it deployed?"
"how do you deal with data access?"
"How do you deal with data migration"
"how do you deal with scaling / concurrency / security / authentication"
etc... broad stroke things.<p>If there are no other devs...look at the code and look around at some of these broadstroke things.<p>One thing you may find is they are using an architectural pattern you aren't familiar with, so be on the lookout for things that look odd but look very deliberate and duckduckgo to see if you can find any information around names in the code. Like if you saw FooActor BarActor, google for Actor / software etc.<p>Another thing to keep in mind when you find odd stuff is that quite a lot of devs copy paste stuff from the internet, and implement partial ideas they have learnt about, so duckduckgo for snippets you suspect.<p>Then the main thing I like to do is take a usecase from the software and follow it right through every layer, either through static inspection, or using a debugger. I then follow up on things that initially seem confusing. I then start sketch out a bit of an architectural diagram ( throwaway )<p>For Embedded systems code I tend to start from boot and draw out a bit of a flow diagram of what's happening.
I’d say the most important thing is to learn the domain and the business you are working with. Never assume the code is doing things the right way for the business. Get to know your client really well and try to understand what they need to software to do. Keep them in the loop as much as possible.
This is super specific to each project but here things that worked for me in previous projects.<p>Two assumptions: You plan to work on this longer-term (not a 1month project stint) and there are things worth improving (eg barely used legacy app might not be worth your time)<p>#1 Get the team on board<p>if there are multiple people you need their buy-in and support for whatever approaches you want to do<p>#2 Plan for "health by a thousand small improvements"<p>it will be an iterative approach and you will refactor as you go.<p>#3 Don't assume different = bad<p>people might have done differently, consider using their approaches. you might do it differently. but it's better if you keep a consistency within the codebase. in codebase management consistency trumps cleverness<p>#4 Create space<p>Consider introducing a fix-it friday where everyone can work on little improvements<p>#5 Create non-blame culture<p>Stuff will break if people risk improving things. Avoid blame shifted to them. If bug trackers ping individual people consider pinging the whole team instead<p>#6 Consider automation<p>introduce linters, autoformating, codemods, danger.js, code complexity analysis, etc<p>#7 Introduce tests<p>This one is the most annoying. But worth doing: whenever you improve a feature a bit try adding a test - often in legacy apps there are no good tests. A lot of people recommend writing a test suite for the whole app before you do anything. If you are lucky enough to do this try it. I always found the iterative approach more realistic as you can also do feature work while refactoring.<p>When doing tests focus on integration (vertical/functional/etc) and not unit tests (unless the "unit" contains critical or complex logic). Your goal is to know "that you broke something" - you get by if you don't always know "what you broke"<p>#8 Acknowledge tech debt<p>not everything needs refactoring. If it's not critical and nobody needs to touch it consider acknowledging it as tech debt. Add larger notes above the problematic areas and explain why you aren't refactoring it, explain things worth knowing to understand the code better, etc. Whenever you leave comments remember that comments should explain "why" not "what" the code does.<p>hope that helps! good luck.
First, get your tooling set up, especially a code search tool with go-to-definition and find references. A good code search tool will make you much faster and better at understanding code, finding correct usages, debugging problems, etc.<p>It also makes it easy to get a URL to any line/region in a code file to paste into email/Slack to ask/answer questions. (Of course, GitHub has URLs, too, but you probably aren't browsing code on GitHub already because it lacks code navigation/intelligence features, so getting the GitHub URL would add an extra clunky step.)<p>Here is a study of Google's internal code search tool with some example use cases and interesting stats: <a href="https://research.google.com/pubs/archive/43835.pdf" rel="nofollow">https://research.google.com/pubs/archive/43835.pdf</a>. Most(?) engineers at companies with large codebases use code search frequently <i>if</i> they've ever tried a good code search tool (i.e., it's hard to give it up once you've used it).<p>(Disclaimer: I work on a tool that does this, but I'm omitting the name/URL because the advice is general.)
Lots of good comments here, but I didn't see a code search tool recommended while skimming.<p>I use this one: <a href="https://github.com/ggreer/the_silver_searcher" rel="nofollow">https://github.com/ggreer/the_silver_searcher</a><p>But the important thing is to be comfortable popping open the console and using it. Makes it so much easier to "research" a particular part of code quickly.
Reading Refactoring by Martin Fowler helped me a lot. The examples are in Java but many of the concepts apply across all languages. However I would say the examples makes the most sense for statically typed languages. I wonder if anyone knows of a book that covers the concepts in Refactoring but with examples in a dynamically typed language like javascript?
Read a lot of code!<p>Spend time reading code in the codebase even if it doesn’t seem to make sense, even if you don’t think you’ll need to know that part of the code. Keep reading until it starts to make sense.<p>My trick has always been to just read. I even avoid tools that automatically navigate the code because I like to just read it until I know where things are.
Apart from what others have mentioned, it may help you to run some stats on the Git (assuming it's Git) repos/code. The most changed files would be the important ones. Modules/Classes with most test coverage would be important ones. Check out for God classes (<a href="http://wiki.c2.com/?GodClass" rel="nofollow">http://wiki.c2.com/?GodClass</a>)<p>There is no better substitute to talking to people though.
Very simple input, but they have served me very well :-)<p>1: Make sure you have development and test environment
available (including data transfer from prod -> test)<p>2: Source control and Easy deployment (to all environments)<p>3: Map the code into importance. (not all code is equal).<p>4: If possible spend time with the main user / product owner (especially in peak periods). You're blessed to have users, who understand your system.<p>And rember code that has been live for 3 years have earned a lot of expirience<p>PS: Typescript +1
1. Assess how much of the code is actually understood. Is there any record of the design decisions, the edge cases, the debugging process, the paths that weren't taken? Who knows the most about the codebase and how it got to be how it is?<p>2. What's the current specification? Don't look at the stack, look at input and output cases. How well does the code meet the spec? Where is it failing?<p>3. Before you change anything you need to know what the change process is. You probably do already know this, but if you don't need to find out whether there are any demarcations of responsibility, even if they're only informal and unstated areas of interest.<p>4. When you have all that, you can start working on the code with some knowledge of the context you - and the code - are operating in.<p>5. If code works, don't rewrite or refactor for style without a very very good reason. And don't do it unless you can change all the "bad" code at once. Otherwise you'll end up with a mess of incompatible idioms that make future changes hard to read.<p>6. Write your own docs as you go. Best case is other people will benefit from reading them, worst case is you'll remind yourself what you were doing six months from now - because you'll have forgotten by then.<p>If you're a junior you may not have access to all of the above, so the fall-back is to find out what you specifically are supposed to do, and where you're supposed to do it.<p>If that's vague or unspecified, I'd suggest studying the code to make your own model of it and then running possible actions past other team members and the client before you make the first few changes - to establish a working pattern.
Get a copy of "Working effectively with Legacy Code".<p>The definition of Legacy Code for the author is "untested code". The book is mainly a list of situations a code base can be in and how to add tests.<p>Once your application is end-to-end tested you can play with the code with better peace of mind. Just adding those tests require you to get all the specifications the app has to fulfill so it is a good way to learn them.
I just happened to write a blog post about this a while ago:<p><a href="http://obdurodon.silvrback.com/navigating-a-large-codebase" rel="nofollow">http://obdurodon.silvrback.com/navigating-a-large-codebase</a><p>Short version: document everything as you learn, master your tools, look at message and data formats before code, follow some of the important code paths, change something and see how the system responds.
Been there multiple times.<p>Before making such judgement, you need to be sure you know the community guidelines for that language being used, libraries, etc. You'll need to get familiar with the language ecosystem so that you're not the one doing things your way. You can not live inside your head.<p>You should never aim for a full refactor but rather try to refactor a module at a time. It might happen that codebase in questions doesn't uses modules but you can start to commit one at a time.<p>The rule I follow is: I work on a ticket and will only clean/modify the files that are relevant to the ticket I'm solving. This way you get more familiar with the codebase has you go and you might notice that some parts might actually be well written.<p>Do not fell tempted to wipe out the old code because it contains a good chunk of specification that got lost in past conversations and is probably crucial to the business logic and/or fixes bugs. Another funny side effect is: might be buggy but actually works according to the spec :D
Never try to refactor everything. Sometimes logic may look like it was implemented incorrectly, but from my experience it may have been written like this on purpose. Business logic can be really twisted.<p>Also remember about scout rule: "Leave Things BETTER than you found them.". It will help you to slowly, yet steadly improve the codebase.
Step 1: investigate. find out where the program is breaking and/or delivering unacceptable performance. This means asking stakeholders "is anything broken? What is wrong with the app? what do you want to change?", reviewing exceptions, and crash logs. Keep in mind that often times stakeholders don't know what they want - determine the business objective and then work from that. Determine where the broken code is, and write narrative comments about what you think it does. If there is documentation, read it. There often isn't any documentation, and often times the comments are useless on a good day. Resign yourself to playing a combination garbage man/forensic psychologist for the next few months.<p>Step 2: triage. determine which broken parts you can get away with leaving alone for the short term, and which parts need immediate attention.<p>Step 3: Fix the most critical broken parts incrementally. If there are no tests (there are never tests...), write a test for each block of code you modify. Avoid wholesale redesigns if possible. make sure that you write tests. Try to avoid getting mad about the previous person's style - focus on getting things working to a borderline acceptable level, writing comments to explain your decisions so you or someone else has a frame of reference. The goal of doing this is to buy yourself time to clean the entire thing up.<p>Step 4: Once the app is working at a baseline acceptable level, examine the codebase and determine which areas (if any) require redesigns, and determine the cost/benefit of each redesign, based on what the stakeholders need, want and expect. If any redesign is necessary, negotiate with stakeholders to buy time for it - your bargaining chip should be an additional feature or two that the previous guy shat the bed on. Basic criteria for a redesign: is the current design impossible to understand? Does the current design impose unacceptable costs in terms of performance or development time? if yes to either, a redesign is probably worthwhile.
You'll come back to the same pieces of code over and over, forgetting most of the details and context each time.
If it takes you a while to figure out, write it down. If you had to use the debugger to find out what's in a map, leave a comment with an example of what the keys and values look like and where they're populated from.<p>Once you have added comments, it lets you hover over a function to remind yourself "This does X to Y when the deposit is a check", so you never have to read the internals of that function again when you're not tracing a check.<p>When you have to go 12 levels deep in the call stack to find the source of parameter Y, make a note in a side wiki so you can recover that detective work the next time.<p>Your knowledge of the code base grows like compound interest when you only have to figure out what each piece of code does <i>once</i> and can skip over it after that.
If you use an IDE, learn and exploit its code-exploration features. Use them all the time.<p>Do global searches whenever you aren't sure how things work. If they aren't fast enough for you, get an SSD. Use them to look for all kinds of things to convince yourself your change is safe.<p>Add comments as you figure things out. For example, "this algorithm seems to match the one at /src/core/foobar.js:123".<p>You can also add "DEBT" or "REFACTOR" to your IDE's list of TODO tags, and use it in comments where you see something you think might need cleaning up. If you mark these places now and change some of them later, you'll avoid doing damage; you'll get a chance to learn more before changing things.<p>Put ticket numbers (Jira, whatever) in your comments too.<p>Think "dig safe". You're spraying painting warnings near significant opportunities to break things.
It's not exactly a guiding principle, just more of an analysis & learning technique: Get ahold of a big piece of drafting paper, or a whiteboard, or one of those big-ass pads of paper they're always putting on an easel for silly brainstorming sessions. Something physical, big, writable, and not a computer. Set it up or pin it up or tape it up, semi-permanently, and use it daily to diagram and map out each new thing you learn about the system and its interrelationships. I'm assuming here that you have the space to set something like that up. If you don't, you're in a 3rd world programming situation and you have my sympathies, but you can always do something graphical within the computer, too, especially if you have a big screen or multiple screens. I just have always found it quicker to do it in a physical medium.
To my experience <i></i>nothing works that isn't directly besides the code / isn't generated by it<i></i>. So schema generation and/or javadoc-like mechanism. Nobody will read or want to maintain separate structures, especially not arbitrary tomes like wikis.
Keep the goals of the code in mind: providing its users value.
It's a tool, even if you think code should be art. The code's purpose is not to look pretty or to get best marks in static analysis. It's this code that earned the company the money they are spending now on you. Clean code pays off in the long run, but might make you go bust in the short term. In the beginning of a project, it's usually a prototype and it needs to prove itself. Once it has generated some value, you can consider either spending time for quality improvements to negate the tech debt, or you re-write it with everything you have learnt from the previous version.
Run the code through in Softagram analyzer and start digging into the structures using the visual browsing capabilities in Softagram Desktop app. There is free trial at softagram.com where you can do it easily if you happen to have your codes in some Git repo in cloud services such as Bitbucket or GitHub... Shameless self promotion this is however, as I work for the company. But that approach I have also been personally using more than 10 years: static dependency analysis coupled with excellent visual dependency browsing. I think some expensive version of Visual Studio has also similar stuff available.
Document everything as you explore it. I'm an advocate for literate programming but accept it's not going to be accepted by most organizations. So I use it as a personal tool.<p>Tools: emacs, org mode, org babel.<p>Create a parallel directory structure, hypothetical project:<p><pre><code> ./src
./project/src/main.js
./project/src/some-file.js
</code></pre>
Create a new directory structure with one org file per source file and one index org file:<p><pre><code> ./project-org/src/main.org
./project-org/src/some-file.org
./project-org/index.org
</code></pre>
(You can organize it differently, this has worked for me.)<p><i>index.org</i> will be a simple tree view of the folder hierarchy:<p><pre><code> * Project Name
Description
** Source Files
*** src
**** [file:src/main.org]
**** [file:src/some-file.org]
</code></pre>
You may add in some notes about the general purpose of each of those files.<p><i>main.org</i> copy the entire code into the main.org file like:<p><pre><code> * main.js
#+BEGIN_SRC js
// all the code from main.js
#+END_SRC
* [[file:../index.org][Project Root]]
</code></pre>
Start splitting the contents of <i>main.js</i> into separate snippets, I don't know Javascript very well so let me make some quick C example:<p><pre><code> * main.c
#+BEGIN_SRC c :noweb yes :tangle yes
<<includes>>
<<structs>>
<<functions>>
#+END_SRC
** includes
#+NAME: includes
#+BEGIN_SRC c
,#include <stdio.h> // [0]
#+END_SRC
** structs
#+NAME: structs
#+BEGIN_SRC c
// structs
#+END_SRC
** functions
#+NAME: functions
#+BEGIN_SRC c :noweb yes
<<some-func>>
<<main>>
#+END_SRC
*** main
#+NAME: functions
#+BEGIN_SRC c
int main (...) {...}
#+END_SRC
*** some_func
This function will initialize a block of memory
to be used as a shared buffer between two processes.
#+NAME: some_func
#+BEGIN_SRC c
void some_func (...) {...}
#+END_SRC
</code></pre>
As you go through this you can make cross-references to other files and functions/structures. Eventually you'll find a smallest reasonable unit. A long, but clear, function doesn't need to be dissected. But a short, complex one, may end up with each line broken out and analyzed.<p>I don't just import a massive code base and do this in one go. Instead I import parts of it and break down all the related files to a particular topic ("How does X happen?"). I trace it from start to end, and then repeat with the next question. Good, modular code makes this much, much easier. The more tightly coupled, the harder it is to understand no matter the method.<p>[0] The comma is inserted by org babel to distinguish from it's on #-prefixed content.
Took me 1 month to be productive.<p>Went in to a large rails codebase as a backend developer in the middle of a v1 to v2 rewrite and it had custom folders with their own conventions on where to put stuff.<p>All that with no documentation except for the setup.<p>What I did was just ask how the app works + specific workflows in front-end side of things and just connect the dots on the backend part.<p>Most of my troubles where on where to put modules because of their existing conventions.<p>Tips:
1. Ask a lot
2. Read the code
3. A debugger helps
4. Make sure you add tests for areas you touch.
When improving existing code, only do gradual changes. Don't do rewrites, don't replace existing code with better solutions in one swoop.<p>This way, you won't be in a situation when the new solution doesn't work in some cases and you already thrown all the code it replaces under the bus. You'll always have a mostly working app.<p>OTOH, if you introduce an alternative solution, finish migrating to it before beginning improvements in other places in the codebase.
On a practical level, getting really familiar with grep/similar for searching the codebase and using a debugger (I like the one built into VS Code for working with Node) will help you when trying to work out how it all fits together.<p>Depending on time and other constraints, upgrading the codebase to typescript would be a great way to both familiarise yourself with it and to make working with it more productive, but obviously you’d need client buy in.
1. Build the code. Don't do anything else until you can build the code.<p>So simple, yet so many places get it wrong. Lazy devs check in code that is broken. Project structures that depend on you having things on your machine and in a particular place. Circular references. You name, I've cursed it.<p>If it's a project that you should be able to check out and build locally, then you should be able to check the code out in any directory and build it. Period.
Are you able to talk to the original author or the most recent maintainer? If so, I'd spend a couple hours reading the code on my own to get a basic familiarity, then sit down with the original author and ask them to give you an overview. They'll probably even still remember which parts they consider bad or hacky, and knowing about that stuff could save you a lot of trouble.
It's a three-year-old code base? That's <i>good</i>. It means that you can probably talk to some of the authors, to figure out what they were trying to do. A big 20-year-old code base is worse, because many of the original authors are gone, and there's been a lot more time for it to be patched by people who didn't understand what the original author was up to.
Has anybody tried software intelligence tools? Seeing the architectural components and control flow of the code seems like a quick way to document the codebase and figure out which “clusters” to study.
<a href="https://en.m.wikipedia.org/wiki/Software_intelligence" rel="nofollow">https://en.m.wikipedia.org/wiki/Software_intelligence</a>
Git blame is one of the best tools for understanding the history and archeology of a large legacy code base.<p>There is nothing worse when you're trying to do solve some problem that you discover a giant reformatting commit typically instituted by a youngish developer.<p>It obviously doesn't remove the history, it just makes it so much harder to actually find out why the code was written as is.
I'd suggest the book [Working Effectively with Legacy Code](<a href="https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052" rel="nofollow">https://www.amazon.com/Working-Effectively-Legacy-Michael-Fe...</a>).
Before modifying an existing line of code, understand what it's purpose is/was. Even if it doesn't appear to have one, or make any sense, someone created it for a reason.<p>Also IDE/search tools for determining where a function is used are great for removing stale, unused cruft.
If you have the time, make sure that you have adequate coverage from a suite of automated tests. This goes doubly so for a dynamic language like javascript. This will free you up to make changes and will make the whole process of introducing changes less nerve wracking.
If you inherit a big code base my suggestion is to always spend <i>a lot</i> of time going through the tests before jumping into the code. Learn about the business logic. What things have a lot of coverage? What broke a lot of caused regressions? You will learn so much.
Unit tests / automated tests are critical.<p>If you're lucky, you will have a suite of unit tests and automated tests with high code coverage. Rely heavily on these tests as you refactor and debug.<p>If you don't have working tests, consider writing them before making any major change.
Fear large changes to existing code. If you come into a large existing code base with a mindset of a smaller one you will cause 3 bugs for every one you fix.<p>Instead always try to make the smallest possible change to achieve your end goals(bug fix/feature etc).
This book is pretty great:<p><a href="https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052" rel="nofollow">https://www.amazon.com/Working-Effectively-Legacy-Michael-Fe...</a>
focus on outcomes. have an objective like better monitoring, better perf, better code coverage, and use that as your guiding principal. make sure any change benefits the customer or your team. avoid refactoring just to modernize, every change is a potential regression. and what is in style now will be legacy in due time.<p>once you decide on the objective, try to divide components up into interfaces so you can test and refactor a component with reduced side effects.<p>set a goal for each objective. like improve coverage 5% a month or no net neg.<p>long story short, be methodical and focus on outcomes
The only thing it gets in my nerves is lack of comments and documentation. The fallacy that code can be remotely as easy to understand as natural language text. The rest I can endure and tolerate.
Get familiar with your debugger. You may be surprised by how deep in a call stack a bug can live. It will also make you intimate with the different ways your codebase is orchestrated together.
I have been there for couple of times now. First thing, I look into it to how to get refactor if i see something here.<p>Luckily, I had one of the best mentor, who taught me how to refactor the any piece of code without failing.<p>It is really works,If this code base test cases. If doesn't have test cases, I think we have take one step back and do small functionality at time and move on from there.<p>Bad of big code repositories is mostly, they are still using some version of framework which is most uncomfortable to new bee for getting their head around.
Rule #1 use the boyscout approach: clean where other left dirty stuff.<p>Sure, many here would argue that "never touch a running system" is a gold rule, but what if the running system is running in the wrong way?<p>If everyone attain her/himself to this rule, there wouldn't be what we call innovation.<p>Clear example: why develop Windows 7, 8, 10 / Mac 10.10,.11,.12.. if their predecessors were working fine?
my #1 working with existing code bases is you need to get debugger working. nothing can explain the processing workflow better than tracing the execution.<p>also having any kind of schemas, protocol definitions and tests can help grasp whats happening in the system.
You can't really. Especially in JavaScript world where velocity is everything. You'd spend at least ~1 year if it is really large and hit all kinds of hacks in the form of callbacks within callbacks within callbacks that are tuned in a way that (mostly) works. I'd recommend you to run away, seriously.
Devil advocate:<p>I made so many rewrites that it can be say is most of my job.<p>My first real project was move a FoxPro DOS app to Visual FoxPro. I probably not read any (old) code at all. The next, move torwards a N-Tier with SQL Server (that was circa 2000). Then move in other company a Fox desktop app to ASP.NET 1.<p>And that's is only counting my first years.<p>----<p>How I could tackle this WITHOUT READING THE OLD CODE?<p>TALKING TO THE OLD DEVELOPERS!<p>If is possible for you, let them talk about how the old app work. Even better, let them (or anyone in marketing, support, etc) explain the problems that this app solve, and the new ones this app have failed to solve.<p>I have the luxury to mostly work with apps with a RDBMS in the back, and rarely fancy (and NASTY) architectures like micro-services. Understanding a RDBMS is orders of magnitude easier than the codebase:<p><a href="https://quotes.yourdictionary.com/author/fred-brooks/31361" rel="nofollow">https://quotes.yourdictionary.com/author/fred-brooks/31361</a><p><pre><code> Show me your flowcharts and conceal your tables,
and I shall continue to be mystified.
Show me your tables, and I won’t usually need your flowcharts;
they’ll be obvious.</code></pre>
-- Fred Brooks<p>So, before get deep in code: MAKE A DATABASE, and PICTURE THE FLOW OF DATA.<p>Sometimes, is even possible to cut a massive amount of (legacy) code that is the result of a iterative development (under pressure and without planning) that result in a terrible "flow of data". Fix the flow, fix the schemas, and suddenly the code is short and easy!<p>Also:<p>Complicated software are infections of a complicated business requirements (ie: company). When something is a pile of mud, NOT FIX THE MUD.<p>Fix the business requirements until it get easier to handle. This also lead, most of time, to a massive reduction in messy code bases.<p>Also:<p>You have applied any of the sensible advice elsewhere. Instead of rewrite, you make testing and all that.<p>IF YOU FEEL IS STILL TERRIBLE AND YOU KNOW IN YOUR GUT YOU WILL GET STUCK HERE FOR ALL THE ETERNITY<p>cut that code without mercy. Not push along when you have, proved is a dead end. I made a mistake like this with a rewrite from a iOS App made by a consulting firm and lost 6 months(!!!!) trying to be reasonable.<p>This cost me the contract? You bet it. However, In the last 2 week I remove almost 60-70%(?) of the code and rewrite it to be more along the Apple guidelines. I still lost the contract but the next team? Finish it in a month.
Grok.<p>Make a small change.<p>Loop.<p>-<p>When you enevitably come across a trade off, choose the one which is easiest to change later.<p>Everything else is just noise.<p>Large changes in legacy systems are often suffer from the second system effect among other problems.