I am working on this project, which will soon contain loads of packages, projects etc. (Java). So, from the start I need to keep track of the high level package and class structure, monitor which class is being called where, so that I don't make it over complicated after 6 months.
What is the right way to go about it? Any tools for this?
The two biggest things, off the top are clear naming conventions and external documentation.
Clear naming conventions: People should be able to figure out, within a reasonable margin of error, what a class, package, or method is for just by reading its name. That doesn't mean you need names like methodToLoadTheXMLFileAndParseOutPhoneNumbersAndPutThemInAnArrayAndReturnIt(), but names like parseNumbersFromXML() are better than parseNums(). The same goes for classes, packages, and projects. Within the boundary of the level of abstraction, names should be self-descriptive.
External Documentation: Commented code is good. Well-commented code is excellent. But even extremely well commented code is only so useful for understanding the bigger picture, and when that's the goal, external documentation is the way to go. Could be word processor docs, fields in project management tools, or any other format, but the key is to have plain, straightforward text descriptions of components at multiple levels of abstraction.
I'm sure there's more that others can add, but this should help.
You can use UML Class Diagrams to have a visual representation of the relationships between your classes and packages.
There are many tools to construct this diagrams. ArgoUML is an open source tool that permits you to build this and other UML diagrams, it even has a reverse engineering tool to generate a diagram from your source code.
Aditionally if you generate Javadoc for your source code, hyperlinks between the documentation for different classes/packages will be generated automatically.
Write unit tests for everything. This will encourage you to have a design where each module is self-contained, and has well-defined behaviors. If you find yourself thinking "how the hell am I supposed to test this?", it's usually a sign of bad design. (This is not a universal rule. Some things are inherently hard to write tests for, and there's not much you can do about it.)
Start with a design!!!
CASE tools such as Enterprise Architect (it's the one we use at work and is OK) etc. allow you to design your classes in UML, design your use cases, class interactions as sequence diagrams. That way you can see the steps that the program should be taking to achieve each use case.
Using a CASE tool like this even lets you autogenerate your code from the design and then reverse the resulting code + changes back into the design.
In short, design and documentation of a projecct should come first. And if you've done a good design your code should be easy to follow.
There's a trick to "easy to understand and intuitive".
It's called the KISS principle.
Keep It Simple and Stupid.
"I don't make it over complicated after 6 months." is a very important thing to say.
You could make it complicated. Or you could keep it simple.
You can keep it simple by -- well -- keeping it simple.
Before you add each feature ("loads of packages, projects etc. (Java)") ask yourself if you're making it simpler or more complex.
If you're making it more complex, then STOP. Stop adding things.
Define the complexity you're seeing. Fix the complexity. Right now before you add one more line of code.
Once you've defined the undesirable complexity and fixed it, then, things are simple again.
This is an ongoing battle. No amount of planning will prevent complexity from creeping in eventually.
Every single feature must pass the "is this adding complexity?" test.
I suggest keeping a good high level desgin of the domains and packages and their connection with each other.
As for specific class documentation and tools, I don't think those are neccessarily an important requirement especially if you are maintining this in a small team or by yourself. The most important aspect is writing good clean, abstract code. If you spend half your time worrying about external documentation then you will be spending half your time not thinking about the code.
In saying this I think re-evaluating high level design concepts can help you keep a level head in writing the code. By high level I just mean not writing down every class, or every method. I would consider instead how groups of classes or components interact, what conceptual layering you have, and the interfaces between those layers/components.
So, in summary to keep track of code and help maintain abstraction, I would follow these steps:
1) Continual review and design of high level concepts using an UML approach or even just boxes and lines.
2) Using TDD on each package to help each package maintain extendable loose coupling code.
3) Some code documentation wher needed but not to get too overly fixated on this as it is more important to try and get your code self explanatory.
4) Constant refactoring of your code if you notice "during writing" that a high dependancy on other modues exist. Try not to leave code in a TODO state if you can help it just because you are under pressure to get it done. This can often lead down the start of messy code.
