What can I do to understand a medium-sized project with no documentation? [closed]

Question

I recently finished college and started working at a software company. They have a main application (consisting of over 2000, maybe 3000 source code files), written mainly in Java and Flex(Adobe Flash Player). It is a program intended to be used by some companies in the service sector to replace their human workforce with something that can be done easier via a computer (like tracking workers, assigning work to them and many more other things). This program was developed about 5 years ago and it is still updated (by fixing bugs and adding new features as new clients want to use this program).

Because I have worked in the past (an year ago) as an intern, my first assignment was to write an algorithm that handles some events automatically (which can also be handled manually by an operator that uses this application). Problem is, the code isn't documented, every source code file ranged from about 100 to over 2000 lines of code, and it is very annoying and hard to understand how to do some things (even when I know, as a pseudo code, what my algorithm looks like). Because of this I have to ask a colleague of my age who has worked for over an year here, and when he doesn't know, I have to ask a senior, which is pretty much occupied and doesn't have too much time to answer. Mainly I am stuck by looking into many source code files and trying to understand what it goes there and trying to find code I can use to make this algorithm.

I am pretty sad because of this, and was wondering if having a medium-sized application (a long-sized in my opinion may have 100k+ files or so) with no documented source code (no comments in files) (actually there are a few files, usually very long ones, who have about 5-8 lines of comment in total) is common in industry, and it is actually my duty to try to do reverse engineering on their code to understand how to do things. If so, what should I do to understand better this application, without annoying my colleagues a lot of times? I have tried to operate this application manually, but there are many events and things happening there I don't understand and I think an operator for a company that buys this program is trained to know how to use it. If not, should I try to avoid such workplaces in the future (and how do I know they follow this trend)?

Answer 1

Amount and quality of internal documentation varies widely.

Given that you're in this situation now, though, your goals should be:

1. Get unblocked. Figure out how to figure out this body of code.
2. Try to improve practices.
3. Filter for this in future interviews if you don't want to do 1 and 2 again.

1. Get unblocked

As this answer says, in many places you would have gotten a code walk-through when you started. Either this didn't happen or it wasn't sufficient, but that's ok -- it's not too late to ask for one now. It's possible that there's also some design or architecture documentation; doc exists in places other than code comments. So ask for that first (it's easier for them to give you something to read than to spend a chunk of time with you). If there's no design doc, or there is but it didn't help, then ask your team lead (or manager) (a) if you could have a walk-through of the key parts of the code and (b) who you should ask to do it.

If you haven't already, also ask your peers what techniques they use to figure this stuff out. Maybe there are some tricks (and tools) they can teach you that will make the process less challenging.

2. Improve practices

Solving #1 helps you but doesn't do much for the next new developer. Plus, it'll get worse over time as the project grows. Y'all have some technical debt and need to start paying it down, and you need to make less debt in the future.

Whenever I need to figure out something complicated or new (a code base, a complicated tool, new Byzantine IT policies, whatever), I take notes. Thorough notes, notes that future-me could understand a year from now. And as long as I'm taking notes anyway, I do it where others can see, like on the company or project wiki. Then I ask other people to help me improve it.

Treat the page not as "shul's notes" but as "design notes about this project". It'll be incomplete and maybe not 100% accurate, but it should be a living document. Ask others to help. Writing a complete design document is a daunting task, but editing in things you know (or notice are wrong) on an internal wiki page as you think of them is easier. Start the ball rolling and ask for help.

That works for larger or cross-cutting or design-intent matters. There's also the micro level, the stuff that belongs in comments in the code. When you figure something out that should have been commented but wasn't, add a comment. As new code gets written and reviewed (you do code reviews, I hope), look for (appropriate) comments and push back a little if they're not there. Try for incremental improvement; you're not going to change a commenting culture overnight.

3. Filter future jobs

If in the future you would rather work for places that already have these clues, there are a few things you can do in the interview process to try to gauge how good they are about this. There's no silver bullet, though, and there can be variation from team to team within a company too, so even if your initial team sounds good, you could move to a different project a year later and find it's different.

With those caveats... here are some types of questions you can ask technical interviewers:

• Ask about their processes. Start general and drill into details as needed. There are probably other things you want to know about their process, like how testing fits in and how they adapt to changes in requirements, so you can fold internal documentation into that line of questioning.

• If they have an API, ask to see its documentation. This won't tell you want internal documentation looks like, but if they haven't even written API documentation beyond filling in a few @param fields in Javadoc, that suggests that there won't be a lot of internal commenting either.

• Ask how they maintain internal documentation (architecture, design, implementation). I would ask it in an open-ended way like that and see what they say.

I don't recommend asking to see sample code; a couple classes out of context, when you don't know the system they're part of, aren't going to tell you much.

Answer 2

You should have got a "Code walk through" with an expert at the start of your job.

If no expert is available then your first task should be "Documenting the source code" to become an expert yourself. Test cases are also a great way to understand how the parts you don't understand are supposed to work.

Now to get back on topic for workplace.stackexchange. Now you know what to ask in your next job interview ("Does Documentation exist?", "Do you practice Code Walk throughs?")

Answer 3

It's common enough and sometimes it's done on purpose, usually however it's just bad practice by the developers which is what it sounds like in this case.

It's purely specific to the company and sometimes the individual developers. Some places have protocols in place which enforce commenting, others don't. Some have their code from a third party.

There is no real way of telling before you get a job what is in place there. But you could always ask at the interviews I guess. Something like, 'is there documentation protocols for development projects?'

Answer 4

'programmers' tend to do this. Software Engineers who have worked in regulated industries never do this.

Even the Agile system requires documentation, although it tends to be comments in code rather than anything official/useful.