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.

| improve this answer | |

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.

| improve this answer | |
  • I am also using the class diagram and this is really very very powerful. I mean that with a non open source such as Omondo I did what I was thinking was not possible. I have a huge project in which we are over 20 developers. Each developers has created few class diagrams to explain what has been done and why. These diagrams are saved in each corresponding package. If the project is refactored then UML is automatically updated etc.. – UML_GURU Jul 4 '11 at 8:16

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.)

| improve this answer | |

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.

| improve this answer | |
  • in agile, ever changing design with distributed teams, its really hard to keep matching design with code – zengr Jun 29 '11 at 20:34
  • @zenger, that is one of the biggest problems in agile, lack of a unified, well-thought out design. I hate the short-term thinking of agile. But I'm a database person and I design for something to work properly for years as database refactoring is difficult when you get large numbers of records in the database. I have never yet seen a good database design come from an agile project. I suppose it is possible for small things, but it seems unlikely to work in any Enterprise level project. – HLGEM Jun 29 '11 at 22:21

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.

| improve this answer | |
  • I agree, i would do that if it was my personal project, but in a team where new people come and go. its really hard to follow that. – zengr Jun 29 '11 at 21:50
  • @zengr: The question says "I don't make it over complicated after 6 months." Your comment says "new people". Please correct this contradiction. Either you're making it complicated (as it says in the question) or the new people are making it complicated, in which case the question is wrong. Please update the question to clarify this. Also, why aren't the new people taught to value simplicity? Why aren't there design reviews with these new people? Why isn't there any conversation on complexity with them? – S.Lott Jun 30 '11 at 9:47

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.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.