An ideal set of documentation for a bigger project [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

Improve this question

If you would get an assignment to work on something like 2 years old project with 200k lines of code, would it be sufficient to you to get one pesky 10 packages 3 components UML diagram and 2 pages of do开发者_StackOverflow社区cumentation?

What do you think is an ideal amount of documentation to get startet reasonably fast, or is there any advice for me to help me with comprehension of virtualy undocumented project with classes spanning sometimes 5k lines.

Thank you for answers.

---

You have my sympathies :) I think the more general issue of "how to understand a new appplication" would make a great community wiki question

Start by reading the source. 200K lines isn't that huge.

Take a quick read over the source. This isn't an attempt to learn everything, but to get an idea of the structure, where key things are mentioned, naming schemes and so on. The idea is to come out with an idea of where things are, so that you can go back and have a more detailed rummage when that proves to be necessary.

I was asked once when reading code in a similar situation what I was doing. It was an interesting question and I had to think about the answer. In my case, I aim to get an idea of the key flows of the application, and the key data structures and how they are managed and changed.

Do you know what the application does or is supposed to do? Does it work? Has it been released? Or is it still in development? Does it even build?

Are there any test suites? If so, review those to get an idea of the functionality. If not, start writing some as you'll need these to give you confidence any changes you make are correct.

What do you need to do with the application? Add functionality or fix defects? In either case, reproduce the "defect" (if it's a feature, write a test case that fails because of the missing feature. If it's a defect, write a test case that fails because of the defect).

Then start tracing through the execution to see where the relevant code is.

Repeat until familiar.

---

I'd echo the other comments here, but I'd also start documenting the source directly with doxygen - it'll really help 'see' the file-structure of the source files first, then you can begin adding comments for application-wide source and library code.

---

Well I would have to say it depends on how well the code is commented. If the code is not self-documenting, then additional documentation would definitely be essential. On the other hand, if the code has been commented thoroughly and function names and variables are self-explanatory, I honestly probably wouldn't even bother looking at any additional documentation if it were provided, but that's just me.