I have no idea what I am doing
Have you recently started a job at a new software company or changed a project? Maybe even after two years the legacy app you maintain still makes no sense to you? This article presents tips on how to get into complex projects quickly.
Ask a narrowed down question
As obvious as it is, the very first question like “how does this module work?” or “could you describe me the architecture of data transfer between all these services and databases?” would take hours to be answered.
If you ask anything, make sure to narrow it down, preferably in a manner “Does this work this way, that way, or the other way?”, so you will get a quick response without taking too much of your peer’s time. It will also look professional, as you are not throwing full responsibility on your peer at the first second you encountered something you are not familiar with. You have thought a bit how it could work, what elements could be involved, etc. Just as you always first Google and then ask on the forums.
If the question is really broad, ask for the documentation or training first, to lower the pressure on the peer you are asking for help.
It would be ideal to not take more than 15 minutes of anyone’s daytime to help you with your problem
But there is no documentation…
Why there is no detailed documentation describing everything? Training materials are not giving immediate income so in some budget scenarios (company struggles in the current quarter) they may appear as a low priority. Especially if the solution changes quickly, so the documentation becomes outdated as well.
While you are new maybe spending some time updating or writing new documentation/training materials won’t hurt. You will lose the fresh view after a couple of months, and the newcomers will appreciate your effort.
Or maybe there is?
If the development documentation is small, don’t just give up. Don’t forget about the business context of the solution. There is a user manual, there are business requirements, test cases, marketing brochures… Maybe you don’t know there are that kind of documents, so ask e.g. a BA or QA about them.
Any material will build a context of the whole solution. If you get an old e-mail with a long conversation started months ago, this is also some kind of documentation and knowledge, even if only the recent e-mail is important to you right now.
Documentation from the code and schemas
There is always less direct documentation available for developers. Sometimes our databases have defined diagrams, or we can make them really quickly ourselves, to see relationships between tables. “Views” can also show us some relationships.
Class diagrams will be helpful on the backend code.
Automated tests are obvious documentation too.
Use the built-in find mechanisms in your IDEs. Use search in e.g. Notepad++ or TotalCommander. Search the source code repository. Script the database into the .sql file and do the text search. Use SQL search tools like RedGate SQL Search. Search through logs. Use a debugger to see the objects, and use the SQL Profiler to see the SQL queries.
Save some search results or search locations, to use them later. Searching will show the connections between elements, important to not break the application when adding new features.
Knowing by coding
From my experience, a good way to better know a solution is to write a feature affecting as many as possible layers of the application. Front-end, libraries, DB, external APIs, WCF services, reporting and so on.
Knowledge persistence manager
After finding all of the documentation, having control over the source code and finding the right elements within it effectively, you should focus on preserving those victories.
Even the simplest text file document will do its job at that point. To save links to the documentation files, training materials, contact information, filenames containing useful code snippets, definitions of new acronyms.
As you stop using certain links from the file, you can remove them. Or you can make that file a new introduction document for newcomers, if there isn’t one already. When facing a complex solution which was developed for tens of years, you are not going to remember everything after the first read.
First do not make it worse for the next developers
The solution you work with may not be ideal, but that is not a reason to lower the quality of the own work. When not knowing the codebase and features enough, one may try shortcuts (copying some code found in another module), or writing a whole module from scratch because “it was a spaghetti code”.
I would suggest something in-between. Try finding an element to reuse, and maybe refactor it if needed. That way an element (function, module, library, etc.) will become better, and you won’t have to rewrite it, introducing your way of coding into the codebase. You will avoid redundancy not copying the whole structure, and by refactoring it a bit you will learn how the original code was working. Slow, but steady improvement.
More to read…
I have recently found an article touching this topic, written few weeks after mine. Take a look: Master a New Codebase in Record Time by Ethan Urie, on simpleprogrammer.com