What are best practices to read high level undocumented and uncommented code?

Question

There are some opensource projects, that have classes and classes without any significant explanation about what the class does and or why is that class needed. For example, classes in the CppEditor plugin for QtCreator. What are the best practices to read undocumented code? Don't read it, is not an option :)

Answer 1

Go through it a method/function at a time, and add your own documentation. Keep revising the documentation as you learn more about how it all works.

Answer 2

I suggest you gather data from all possible sources.

• Use the code and begin documenting it yourself. Naturally you'll need to read the code to figure out how it works, but also figuring out what the code was intended to be used for and actually using it that way will help you understand. How well you can read code entirely depends on how comfortable you are with the language (or type of language) and the algorithms and patterns being used.

• Read the documentation that surrounds the code. Does the code that calls this code have documentation? Does the code that is called by this code have documentation? Collect as many nuggets of information you can find. This may be obvious, but look for documentation that is not attached to the code, whether it's an official manual, a FAQ list, or blog posts.

• If the code still eludes you, or you have some questions, ask the people who wrote it. Go through the commit log and figure out who wrote the code and see if they are still accessible. Then either email them or the project's mailing list asking if someone could explain what the code does (especially if it's not obvious) and how it was intended to be used. Ask your specific questions and explain your desire to write the documentation for it.