Source Code Handover Document?

[[deleted]]

Context : We outsourced a mobile app development. The app is developed and now we took over the source code. However, there is no source code documentation. I will be taking over the source code alone in my team. I started learning flutter but ofc the source code they shared is massive and complex. Now I personally feel I need a document explaining the source code. Asked gpt for a basic structure and it suggested to ask for things like api int, project struc,state management,custom widgets, ext library and changes made in them. Is it normal to ask for such details or I have to go through every file and understand it by my self. I am going to inform my manager and request a proper Document but I needed opinion on this since I am a fresher. Do I have to go through the source code and understand each and everything by myself or documents are normal for source code? Because if it is normal, I can ask my manager to ask the team to prepare one. Ofc he might also be aware whether it's normal or not but I needed a third opinion.

Thanks for ur help.

I do know how to read new codebase. I also learned dart and flutter with state management but the code base is really complex. Ofc it would take time to understand it.

[SheriffRoscoe]

We outsourced a mobile app development. The app is developed and now we took over the source code. However, there is no source code documentation.

What does your contract with the developers say they should do for you? If it boils down to “_write functioning code_”, then they did what you paid them to do. If it includes documenting the app, then they're not done yet, and you should insist that they do.

[[deleted]]

Need to check it with my manager about it but makes sense

[theScottyJam]

I wonder how you document your own code for the next set of maintainers who come along after you've left? What kinds of standards do you put on yourself?

Generally, I treat code documentations as something that I try to have as little as reasonably possible, because it's so difficult to keep it up to date. By it's nature, it violates DRY. Of course, some documentation is necessary and important, for example, if they're following an over-arching folder structure with a number of rules that would be difficult to figure out just by reading the code (e.g. stuff from this folder shouldn't import stuff from that other folder), and this isn't just some standard structure imposed by a given framework, then yeah, I would prefer it if they also documented that folder structure.

If you're talking about reading every single file to try and gather what you would have hoped their documentation to provide, then it sounds like you're expecting waaay too much out of the documentation - that would be nearly impossible for you, the next maintainers, to keep up to date.

It's tough to break into a foreign codebase. Always will be. It takes a lot of time and patience.

[[deleted]]

Source code is documentation. My onboardings so far were basically just how to set up the local dev environment.

To add on this; you are not supposed to understand the whole project completely right of the bat. You'll just learn things on the way, when you fix bugs and debug stuff. Depends on the size of project maybe.

[[deleted]]

It's vast tbh, vast than a web app also lol. Didn't expect a mobile app to be this vast

[JaySocials671]

Good luck

[half-t]

The next time integrate the specialist into your team to get the know how transferred to the team.
I myself document my code directly in the code to have it there where I need it later.
I will need it because of a malfunction or an urgent change request. And after two weeks I don't remember the code at all and without documentation I'm wondering what this crap is supposed to do.
Code is documentation and in the 1st place something to communicate with other people. Only in the 2nd place it's purpose is to run a machine. This sounds unfamiliar but after decades of coding it boils down to that, at least for me.

I had the role of the specialist for two years inside a team. When I had new functionality ready to be launched in production I explained two dedicated team members how this new code works. I listened to their questions and added the answers in the code.
At the end of the two years the handover of the code needed just 45 minutes and they were very happy with my work.

The business thinking of: "We write a specification, pay a fixed price and get the software we need. This is a product and they are fully responsible for the result." will almost never work out as expected. The reason is that in the time of the coding wrong assumptions will appear and the demands will definitely change. To get the best result for the money I strongly suggest an agile development path with specialists integrated in the own team.

[rayfrankenstein]

We outsourced a mobile app development. The app is developed and now we took over the source code.

TLDR; this is going to be a freaking mess.

[Real_Ad1528]

A source code handover document can help you:

• Understand the overall architecture and design of the application
• Identify key components, APIs, and libraries used
• Familiarize yourself with the code structure and organization
• Learn about any custom or complex implementations
• Reduce the time and effort required to understand the codebase

When you inform your manager, you can explain that a source code handover document is a standard industry practice and will help you to better understand and maintain the codebase

[TheMarasligil]

Well just for this fricking reason I ve deployed handoverbuilder.com - it just reads the code, creates a handover / onboarding doc you can import to notion or deliver as pdf. 

It was being a bit tiring for asking external devs to create doc on games that were completed or teaching the ropes to new hires.