How do you read and write a project beyond a one-page script?

Question

I have hit a plateau in learning to program in that while I know CS concepts and I can read and write a program such as a diminished find clone, I cannot create anything that's spread across multiple files, and making meaningful changes to something already existing requires some comprehension that I at present lack. When I start reading a new project of someone else's in hopes to make changes, the first, hard, step is that I usually literally do not know where to start, as in which source file to read first, especially if it is a language which has nothing like a Main class. I have done some inconsequential projects in Java before requiring multiple classes, thus multiple pages and no obvious start, but these projects were all small enough for me to hold the entire project in my head.

What's the next step? How do I learn to work beyond making one-file scripts with one or two supporting and header files?

Answer 1

For a language like Java, the way out is to pick a project that isn't just the solution of some equation(s) or a similar mathematical problem. Find a project in which the description of the problem can be analyzed as some "thing" that has discernible "parts". The parts can be modeled as classes and the resulting objects composed into a solution.

One that is simple enough is a calculator. A calculator has a display. It has keys that have actions, which vary depending on the "state". For example, the "5" key behaves differently in the case that the previous key was an operator or another numeric key. The answer of Ben I. mentions design patterns. This is an example of the Strategy Pattern.

Most calculators employ a stack or other hidden register beyond the display. Calculators have an operational strategy of operation that differs for an RPN or an algebraic calculator. The precedence of the operators may be important, or not.

The calculator can print out a tape of recent operations, or not. It can have a GUI or not. If it has a GUI then you can build it with MVC or not.

And if you want a real challenge (the Polymorphism Challenge = writing a program with a limited budget for selection statements), it is possible to build such a thing without a single "if" or "while" statement, provided the user gives the key presses. This will give you very low Cyclomatic Complexity, which is a desirable feature of any program.

But it is the "parts" composed into the whole that is the essence of this.

---

I've purposely not provided pointers to some of the terms here. You can explore them on wikipedia or elsewhere. But the polymorphism challenge search will lead you astray. Look HERE for guidance.

---

And using JavaDoc consistently is a good habit. If you are extending an existing project then the JavaDocs already (hopefully) in place should be a good guide to the operation.

Answer 2

It's a little hard to know how to answer this without actually sitting down with you and talking, because there could be so, so many things that are standing in your way. Here are a couple of guesses and hints:

If you are working within an OOP paradigm, then the place to start is with the names of the classes and their APIs (the public-facing method signatures). Some classes within a large project, and their primary use-cases, should become immediately clear just from these details.

Only after I have at least attempted to get a sense of those structures would I turn to public static void main(String[] args). Often, that will be enough to get you going.

Now, as OO projects get larger, it becomes increasingly difficult to interpret their behaviors by looking at the code. The authors of "Design Patterns - Elements of Reusable Object-Oriented Software" likened determining behavior just by looking at code to figuring out how an ecosystem functions just by looking at animal taxonomies. The details are there (in theory), but much of the structure of design patterns is to allow the flexibility to choose behaviors and objects during run-time, so looking at the code outside of runtime can shed surprisingly little light.

In such situations, it helps to have studied object design patterns so that you have a fighting chance of identifying the patterns you're seeing. Documentation, if it exists, can be very helpful. And, as much as possible, you will want to keep the classes, class names, and APIs in mind, and only delve into code in order to understand pieces of that larger puzzle -- that lofty level is is where the heart of the logic is for such programs.

Oh, and debuggers are your friend when trying to capture and understand runtime behaviors!