Reviewing old code database, how to start interacting with the dev team?

Question

TL, DR: There was this software product being developed in my company, I needed to review a lot of the codebase. How do I talk to the development team?

The not-so-short version:

Due to several reasons (which include lack of documentation, not knowing the programming language, travels and vacations making people unavailable), I had decided to do a lot of code studying on my own. Now I need to start communicating more properly with the devs, but I’m unsure what the best approach would be. I’m sensing that “my homework” to understand their codebase is nearly done, with “question-time” approaching.

Without sounding invasive, nor bossy, nor overcriticizing, how can I approach them to:

1-Ask questions about specific code parts (I have a big pile of notes full of them)

2-Inquire about features and parts, which are I believe are mostly unfinished

3-Ask about maintenability concerns I’ve raised.

4-Point out quality problems that might have come from open-source tools.

5-Ask for better documentation.

Context notes:

1. I’m suspecting they are overprotective of their code
2. I know they are not used to having a manager (not for reviewing/criticizing or pressing for deadlines)
3. I don’t know them well personally, and I’m not their boss, we don’t work in the same room nor have lunch together.
4. I know they’ve had lot of issues with their development, most is not their fault, yet I’m not exactly there to help.
5. They have some limited reviewing process, which basically amounts to checking if the code works on someone else’s machine. They’re not used to someone checking code quality.
6. They often give dismissive answers to questions during meetings (“do you have a function for doing X?” - ”We have functions for anything we want.”). Other people have even pointed this out during meetings.
7. Their product is severely behind schedule.
8. I haven’t spotted any actual bug, nor something obviously wrong. I’m guessing I have nothing helpful to offer them in exchange for their attention. Ideally, an answer that does not involve expecting management to intervene is preferred.
9. Most of the parts that would reach the interface between our products are apparently not done, yet they aren't reporting this.

So a few practical approaches could be:

1-I randomly mention pieces of code and bring up questions, as if I was casually walking by and remembered to ask a question. This would sound weird, maybe invasive, and I’d likely receive dismissing answers. Also, they're known to give dismissive answers.

2-I could schedule a meeting with the junior dev, and walk with him through my notes. The meeting setting would provide more focus on the conversation, but I’d understand if he felt like he was being over criticized. I could split the notes over a few meetings, but then every meeting would be harder than the previous.

3-I start posting issues in the versioning tools and/or making silly pull requests to their code base (typo fixes, insert better comments, so on). I guess this would be annoying for everyone, and if they actually rejected or stalled a pull request with no explanation, I’d feel quite offended. But a few of my complaints might call for a “then do it yourself” response.

What I want/need to achieve is: I want to know their code base relatively well and have them recognize this. I need to be able to ask delicate/specific questions and receive honest, concrete answers. I would like them to improve their coding standards and documentation over time.

Answer 1

If you need to integrate with their code, why not treat it as a black box?

If you specify what outcomes you need to achieve and ask them to outline how to interface with their code to achieve the desired outcomes, rather than reviewing the code itself. In other words, ask them for a detailed spec (similar to a service contract from an API perspective) rather than to explain how their actual code works at a detailed level.

Is that viable?

Answer 2

I think you are approaching your task from the wrong end. If your goal is to help drive better coding standards, that won't be done by questioning the existing codebase. You have to lead by example to achieve that, and be able to explain why the way you did a specific piece of code is better than the previous one.

There is no reason for you to learn the old code, or to question all of it. It's not like there is a budget to go and rewrite/refactor all of it, now, is there? Although if there is, then my focus still would not be on the existing implementation, but instead on gathering business requirements and then validating whether the code meets them. This will also create clear action points of what has to be improved and how, and as the new code is written - that is the time to enforce better coding practices through pull request reviews.

But just questioning the entire codebase I don't think is productive, and your current goal will only earn you ire from the developers, not awe and respect, because criticizing is easy, guiding, and mentoring towards the better, often by example, is hard.

Answer 3

Only by scanning through the comments I found out what apparently your problem is: You need to write software that integrates with the existing software.

You shouldn’t have to look at their code at all, and the code quality shouldn’t matter to you. What you need is clearly documented interfaces. And if those clearly documented interfaces are not there, someone has to create them.

What you need to do is to talk to someone who is in charge how you get what you need. Someone who can say to the team “xyz needs to be documented, and that has higher priority than tasks a, b and c”. And you would probably the right reviewer for this task.

Answer 4

What’s your goal here? All I’m seeing from your question is personal education as I’m not seeing a business goal (e.g. need to learn the code base because I’ll be developing the product with the group, writing test cases etc). The developers only have a certain amount of time in a day, and given the choice between the goals put in front of them by their boss OR satisfy your intellectual curiosity, which one would they choose?

Communicate your goals on why you’re doing what you’re doing and if the developers see some upside to the idea, they would highly likely work with you to get that accomplished.

Answer 5

First of all, the project needs documentation - not just documentation for users, but documentation for developers. That's where you're supposed to start, by reading through the documentation.

This documentation is not simply a list of classes/functions, not simply a doxygen-generated list of comments from the code, it needs to have a good general overview of the architecture, the modules of the application, then down to the next and next level, components, classes, their interactions etc etc

If that documentation does not exist, that's the first point that needs to be corrected - they need to make it.

If the company does not want to allocate the time even for the basic architectural documentation to be written, then they probably won't allocate time for anything else either, and then the situation is hopeless. (and the question is why are you doing it at all?)

The question is whether the developers did not write docs because they did not want to... or because the company did not allow them the time to do it, and kept asking for more and more features, ignoring the long-term needs for documentation, automated tests at all levels (unit, component, integration etc), proper code review and everything else...

If the company did not allow them the time for it, and now you come and ask them for it, they will (understandably) not like that one bit.