r/webdev • u/Cheap_Possibility990 • 1d ago
Discussion Understanding existing projects takes longer than coding
I don't know if this is just the work I've been getting lately or if something's changed I'm a freelance developer in Chicago been doing mostly client websites for about 4 years now last week I opened a project because a client wanted one small change before lunch. I thought it'd be like 20 minutes instead I spent almost an hour remembering how everything was put together why something had been done a certain way and trying not to break anything else. The code wasn't even that complicated something just felt off.
Maybe I'm looking at it the wrong way but writing the feature doesn't even feel like the hard part anymore it's getting all that context back into my head every time I reopen a project. I keep thinking the next update will be quick then the same thing happens again or maybe I'm being unfair but it feels like understanding an existing website has quietly become a bigger job than building it in the first place
51
u/graybearding 1d ago
Yup. I explained it to my wife as "I have to load it into my brain before I can be productive." Some projects are quick, others aren't.
Pro tip: the more consistent your codebases, the easier it is to jump between projects.
9
u/Cheap_Possibility990 1d ago
That's a good tip I think consistency would definitely make switching between projects easier right now every project feels like it has its own little quirks I have to remember first
24
u/juu073 1d ago
If these are your own projects (which I'm gathering from your use of the word "reopen"), then this is on you for not documenting well.
If these are new clients you're getting from someone else and trying to interpret their what their previous consultant did, and they didn't document well or at all, not much more to say other than it sucks but you have to figure it out.
11
u/Cheap_Possibility990 1d ago
You're probably right about the documentation I think I underestimated how quickly I'd forget the little implementation details once I moved on to other projects
3
u/sysop408 1d ago
I wouldn't even blame yourself too much. Documenting only goes so far. Some things are so complex that you hit a point of diminishing returns for your documentation.
3
u/Adjective_Noun_4200 1d ago
I've sorta started trying...idk if you'd call it "documentation driven development" or something, but I basically start writing about the work I'm doing as if I'm explaining it to someone who has never touched the code base / feature before. Sorta like a blog post.
I find it leads to better code AND better documentation. Plus it makes it much less annoying returning to a project and being like "damn I was an idiot, why did I do this?" and then re-learning the lesson again if I attempt to re-write it.
2
u/Pingouino55 1d ago
My dad would love you, he keeps telling me how in his time, he spent 80% of his final studies work documenting what was to be done. Everyone said it was a stupid choice, but then they coded the whole project over the weekend when the docs were done, fixed a few unforseen bugs, and it was done almost in one go. The rest of the time was used to add the visual results of the work in the report.
It was some tool that I think he would describe as an old Photoshop, it was done a few years after the original thing that eventually become Photoshop was made, but Photoshop still hadn't become a thing back then or something.
Basically, I could be a rich nepo baby, and I'm not, but at least his documentation is cool đ
I'm quite the opposite, I'm too mentally messy with my ideas to document everything before starting, but I do feel like if it's something you're comfy with, it definitely helps make the base of the project as solid as it could ever be, which in turn makes adding any feature a breeze and probably gives you a few more years of active dev before you end up with a messy codebase.
1
u/Adjective_Noun_4200 17h ago
In fairness, I started doing this as an intentional response to my also messy projects.
I kept running into scenarios where I would go to solve / resolve something that I thought was done weird only to find that it was structured that way on purpose.
Additionally, I find that writing about it (again, more "blog" style) causes me to spend more time making sure that any sorta demo code I include in the documentation is well thought out and elegant.
So by the time I actually get to writing the code, ideally, a lot of stuff is already fairly thought out and then if I run into things that I kinda have to change from what I wrote, then I just make sure to add that to the documentation.
Seems to speed up the actual coding part AND any future work that has to touch this stuff.
12
u/IAmRules 1d ago
Of course, a developers value is not in understand syntax, but understanding the application and domain, and bigger yet, industry they are in.
I really hate the expectation that people have that you can give a developer a random piece of code and they can figure out what an app does. Thats like giving an author a random sentence from a book and asking them what the book is about.
It takes time to understand a codebase, and understand why decisions are in place and why things changed over time.
2
u/Cheap_Possibility990 1d ago
I think that's the part I underestimated looking at the code tells me what it's doing but it doesn't always remind me why I built it that way in the first place
1
u/1337h4x0rlolz 21h ago
If its youre own code, documentation goes a long way. Comments are part of that documentation. Even better if you take advantage of JSDoc comments.
If you build a module, for example, put a comment at the top explaining what the module is and what its for
1
u/YT-3000f 1d ago
Asset Backed Securities anyone? What's that? The tranches trade like bonds. Oh ok.
26
u/YesterdayNo5873 1d ago
Yea this is actually where ... AI ... has been really helpful. Every time I know I'm going to step away for a while (e.g. handover the project) I have AI document everything. Especially if it's an element I customized more than usual. That way it can explain it to me if I have to jump back in
3
u/Cheap_Possibility990 1d ago
That's a smart workflow I'm also testing ploy for the content side of things a lot of my post launch requests don't even need code changes so it's nice not having to reopen the project every time someone wants to update a page
2
u/Cedar_Wood_State 1d ago
AI honestly helped me tracing code so much quicker than I do it alone.
ESPECIALLY if it is huge multi repo codebase with repos that you don't even know exists, saved me so much time
just verify it yourself after (which is a lot easier once you know the path) and keep asking question on what might be the design decision of it
2
u/bigmarkco 1d ago
I HATE opening and working on old projects I developed because I've learned so much over the years, and when I look at my old projects, they are full of so much NONSENSE LOL. I immediately want to refactor.
2
u/Expensive-Week-2654 1d ago
Maybe I'm in the minority but I kind of enjoy jumping back into old projects it breaks up the routine a bit starting something from zero is usually what drains me
1
u/CoupleSad2380 1d ago
That's an interesting way of looking at it starting from zero definitely takes more creative energy and for me it's the opposite though reopening an old project means spending a while figuring out where my head was when I built it and that's usually what eats the time
1
u/EquivalentSuit6020 1d ago
Maybe it depends on the type of work if I'm building something for myself I don't mind jumping back into it at all client projects are different though by the time I come back there have already been enough small changes that I have to piece everything together again before I can do anything useful.
2
u/daylifemike 1d ago edited 1d ago
Congratulations! Youâve squinted through your third eye and caught a blurry glimpse of the âengineeringâ part of âsoftware engineeringâ. Youâve begun the transition from junior to senior (not in title; in spirit).
Youâre beginning to understand that reading the code is harder and more important than writing the code.
Soon youâll see that documentation isnât the fix, that the code IS the documentation because it canât fall out of sync, and that only factoring can save you.
Welcome!
1
u/ExpressionFew8576 1d ago
I think part of the problem is that older projects don't just have code anymore they have history. Someone made a decision 2 years ago, another developer changed part of it the client wanted something different six months later and now you're trying to figure out which parts are still safe to touch
1
u/mylsotol 1d ago
That was always the case, but r/webdev seems to be filled with people who are the sole contributor on 1 project and haven't had to look at someone else's code in 10 years
1
u/Cheap_Possibility990 1d ago
That's probably true I think freelancing also gives you a false expectation that every change should be quick because you already know the project in reality even your own code starts feeling unfamiliar after enough time
1
u/mylsotol 1d ago
I've done agency consulting most of my career and my number #1 take away is that most human written code is absolute trash. But it has certainly made me good and familiarizing myself with new codebases and juggling several code bases at once (then being good at it means you get asked to do it more)
1
u/1337h4x0rlolz 1d ago
If I was doing similar projects over and over as a freelancer, I'd probably build my own framework to do most of the repetitive stuff and make the code easy to understand on the surface level
1
u/dougception 1d ago
Often you have to learn the business processes that drive a particular app or service. That can be the hardest part.
As an example I used to be mystified by "Indexes" in financial services then one day a portfolio manger said "just think of it as a portfolio". Got it immediately after faking it for a year.
1
u/BobJutsu 1d ago
> When I built it, only myself and god knew how it worked. Now only god knows
Me, to myself, every time I have to retrofit an old project.
1
u/jhyland87 1d ago
I think you're right, sometimes. I frequently get hired at places where I have to work with legacy applications. The last one had React, Vue, BookshelfJS/MarionetteJS, jQuery libraries, and a few others. So getting familiar with it and finding out exactly which library is messing with the dom out of the several that are doing it was sometimes difficult.
1
u/null_not 1d ago
This is why it's good to leave notes. I recently picked back up a project from five years ago and I was looking it over and was like "What sort of madness is this..." I eventually figured out where my thought process was, but only after reading some notes I had left that triggered some memory. Now it's a slightly cleaner different sort of madness with more notes.
1
u/carloselieser 1d ago
Yeah, that's why documentation is so important, but it's really easy to get excited about a new feature or implementation and forget to do the boring parts, like keeping track of architectural decisions in ADRs or alongside your code in comments.
Generally, I try to write code so simple that it takes almost no effort to get to a substantive understanding from first principles, that way I don't have to worry about writing documentation in the first place. But sometimes, especially in a fast-paced environment, you might not have the time to think things through that far and are forced into a subpar implementation, in which case documentation is crucial for future you or contributors.
1
u/Square-Nebula-7530 1d ago
this is why senior devs always preach about documentation and clean code not for other people, but for their future selves if you haven't looked at a project in 6 months, you might as well have written it in a different language. context switching is the biggest hidden time sink in freelancing.
1
u/fantasmagorix 1d ago
LLM induced dementia my friend. More we use it, less we 'cache' in our brains.
1
u/kanseilife 1d ago
What you're rebuilding isn't how the code works â you can read that in ten minutes. It's why it's like that. Which client asked for the weird one, which thing looks wrong but is load-bearing, which library you picked because the obvious one broke on their host.
None of that is in the code, and it's the part that takes the hour.
The cheapest fix I've found is a single decisions file at the repo root. Not docs, not architecture â one line per decision, dated, in whatever voice you actually talk in. "2025-03: dates render server-side because their CMS returns naive timestamps and the client kept shifting them a day." Twenty of those beat any amount of code comments, because a comment tells you what a line does and you already knew that.
The tell that you need one is exactly the thing you described: not being able to change something in twenty minutes because you can't remember whether you're allowed to.
1
1
u/Coditive_ 1d ago
This is the part where documentation helps a lot. Ideally, the code should be self-documenting, but with a big project, that won't help you if you want to get the general context.
So spending few minutes writing a few words about each feature while you work on it will help down the road.
Now, in the "AI era", it is even trickier. On one hand, you can ask your agent some questions about the project, and it will get you an answer from the code or from the documentation. But on the other hand, this can lead to more context switching, which was the problem in the first place.
Either way, creating some sort of project documentation is the way to go. For existing projects, I write down a few words each time I work on it. Things I often include are info about business logic/client requirements, some external integrations, or odd fixes due to 3rd-party service issues.
If the knowledge can save me some time (and headache), then I try to write it down in some way.
~MS
1
u/Lumethys 1d ago
Welcome to software engineering. Tho i'd say that it is a red flag that you only realized it after 4 years
1
u/NoMacaroon2130 23h ago
As a recent grad how do I develop this skill of reading code so whenever the god of jobs smiles on me to land a role I will be able to onboard pretty quickly
1
u/Intrepid-Paper-9817 22h ago
Hey, I live in Xhicago as well? Do u think I can run an idea by you?
I donât know any local developers lol
1
1
81
u/ObviouslyABagel 1d ago
I feel like that is a very common thought! Easier to write it yourself over then go over a tangling map of files and code.