dear all,

I have been using C++ for quite some years now and I think I can say I'm well acquainted to OO principles, encapsulation, generic programming , ... I have however never participated in large software projects where several programmers work together on the same source tree. I've never worked with CVS for example, except for downloading apps. I am thinking of writing a professional database driven application, but I'm afraid the code will rapidly become a maze of classes of which only I know the coherence. The code would not be comprehensible for other future developers and will therefore be unmaintainable.

the questions:

Is there some good textbook that describes how to structure a large C++ program so that maintainability and future expansion is ensured? I don't need a book which describes C++ syntax, but something that describes how the 'architecture' of a professional software project should look like.

What can be considered a good open source example project (preferably something using a database) that is structured according to the previous mentioned principles and for which UML diagrams or something alike are available?


thank you for your help

There are a lot of books, that discuss this subject and I've read several of them. The gold pieces, that I recomment highly, and that no (software developer's) bookshelf should miss are:
-"Agile Software Development, Principles, Patterns, and Practices (Hardcover)" by Robert C. Martin
http://www.amazon.com/gp/product/013...Fencoding=UTF8

-"Domain-Driven Design: Tackling Complexity in the Heart of Software" by Eric Evans
http://www.amazon.com/gp/product/032...Fencoding=UTF8

-And last but not least: Every book of the wonderful Martin Fowler about this subject; they are all great and especially the ones about refactoring and/or patterns are a must-have!
http://www.amazon.com/exec/obidos/se...0&Go.y=0&Go=Go

Common sense really. Here's my method:

I always spend a good day or so at least commenting my code. (for significant work)
I hate going back 3 months later and thinking "WTF?"

Do it when it's about wrapped up, as there's nothing worse than comments
becoming out of step with code as it evolves (i.e. misleading or WRONG comments!).

If it's significant I go back a week or so later and review it, as
when you are close you assume knowledge and what seems obvious at the time, isn't quite so
a few weeks later.

Lots of comments on what data is expected IN and what comes OUT.
Comment process not the actual code.
As few comments in code as poss. Keep the code simple.

Make test data as you go. Even better a test program with data
and instructions so you can quickly get going if you need to debug.
make HOWTO's, or makefiles maybe to run tests or examples.
(it speeds development too)

remember, 33% of the channel tunnel digging effort was for future maintenance purposes.

Two really important words in any large project - "Design Documentation".

Document the heck out of any project that you work on. The interface between layers, the external and internal code and data flows, all the way down to pseudo-code if you have time. Believe me, taking the time upfront on a large project more than pays for itself in ease of implementation later on. Also, once you have the initial design down on paper, you can easily "farm" out portions to other team members and be assuered that everything will come together during the project's integration phase.

To Fleysm

Very interesting, the books you suggested.

I'm curious about UML and Case Tools and such, but the three books you suggest don't out and out state "I am a UML Tutorial" or anything along those lines. Their descriptions in Amazon sound philosophical, almost metaphysical.

I've downloaded two UML tools, Fujama & Bouml, and would like to start typing right away. I've got experience with C++ and Java, just no UML.

Can these books really show me how to use UML in software development?

For UML I'd suggest the UML Distilled (Martin Fowler) as an overview of OO techniques I've yet to find anything better than Object-Oriented Technology: A Manager's Guide by David Taylor.

Your book suggestions

The UML Distilled book and the few pages I saw in Amazon are promising. I'll get that one.

Does this book use examples?

However, that second one sounds like a philosophy essay. I already know what OO is and does. One must in order to do C++.
And this book doesn't even have 'UML' in the index.

The Taylor book is not a UML book. It is a book about OO and if you are confident with its terminology and uses then you possibly would not gain much from it. However, to be good at UML you do require to have a solid understanding of OO, which is not something you necessarily need to have to program in C++. C++ is not an OO language it is a language that supports OO.

From an OO programming standpoint, Design Patterns: Elements of Reusable Object-Oriented Software (Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides; 1994) is absolutely essential. When the ideas first came on the scene, Object-Oriented theories promised so many features, like reusability and modularisation, that many inexperienced programmers just can't seem to manifest in their code. This book can help you write code that brings out the best features of OO design ideals. I have found it an excellent reference when trying to come up with the "best" way to organise my code. It contains some examples in Smalltalk, and many more examples in C++. Most of the book is a design pattern "catalog" that lists more than twenty differen patterns after which to model your code. Each pattern has a discussion on its strengths and weaknesses, where to use it, extensibility, etc. I'd recommend strongly considering it, not just for your current project, but for any reasonably sized work in an OO language.

to taylor_veneble

What a coincidence. I have your Gamma, Helm, Johnson, Vlissides book, "Design Patterns" on my shelf here and even though I bought it one or two years ago, I can't get off the ground with it.

What I need is a simple "Hello World" type of example in this vast sea of Design Patterns, OOD, OOP, UML, Case Tools etc. Something real, concrete and visible.

This book "Design Patterns" chatters and prattles and mumbles and grunts for 50 pages about thick, dry, abstract ideas and platitudes before writing a single paragraph of real C++ code.

What can a person do?



P.S. If you really want to have fun, then try to read one of the Addison-Wesley books in a foreign language.

I never been in a big project myself (at least, not as a team work anyway) but I found a few things that do _not_ work well in my projects and I would like to share if that's ok

- UML: While a good way to visualize your program, classes and methods before actually writing a code, a medium-large size project in UML can actually be more of a pain in some cases. First, you lose a lot of time doing nice class diagrams. Second, once you start to code, more often then not you will take a different approach with your code, meaning that it will not be very "syncronized" with Code/UML.

What I do?

I design very basic UML diagrams, just to get a few of the "structure" of the code. For example, in an ordinary class-diagram, I simply put the class name and eventual method name. I don't actually describe all variables and it's data type, nor what the methods return. This helps a lot even outside programming. Yesterday, I was designing a simple database to handle costumers and orders. I had a little trouble linking a order table with a product table. A simple UML diagram fixed the problem.

- Commenting too much code

Again, overcommenting a program can make things a big mess and just like in UML, it will come a time when you run a few reafactors and your comments won't be in perfect sync with the actual code, making it harder to read. I've noticed that Java programmers usually make more robust programs than C programmers (No pun intended, I will explain this later), in the sense of "not being afraid" of classes and methods with long, descriptive names and less commenting. I, for one, believe that a program does not need any comment, just like a well designed GUI does not need any explanation of how to use it. Example:

// This method saves the game
public static void C(String a) {
//
}

I read a lot of C code written in a similar fashion(I do know that the above is Java). I found this a better solution:

public static void SaveGame(String fileName) {
//
}

I agree with this! -Every time when a comment is needed you should consider to wrap this section in a new function that is named like the comment you would give, ...as you just told. This is especially true for all the one-line comments I see everywhere, when I look through foreign code. But it is no option for the general comment-block, that every function should have at the beginning, especially if you want to use some kind of automated docs-generation. -And that is invaluable if you expect that someone else will work with you code!

Here I do not agree: When you work in (or even manage) a team, you need a way to communicate with each other, you have to tell your colleagues how your piece of code works, what the interfaces look like, how it interacts with other code and so on. For this communication a good knowledge of UML is essential, because this is the language that everyone speaks. So UML is not made to make you understand your own code better, but to let others understand it. I guess everyone (who has experience with this) will agree that it is so much easier to re-engineer foreign code, if there is a well made UML-booklet with it.

But UML is just a tool, that is used to describe the internal structure of a program, and only a good knowledge of this does not make a good developer. So if someone is interested in learning to manage large projects or build good "public code", he needs more then a book of UML. So you usually have to buy more then one book. And for this I can only refer to my first post of this thread, where you will find a good mixture of UML-, patterns-, refactoring-, and "basic understanding of large applications"-books. For me they were all great and I learned more from them, then from any other.

Thanks for you input on my thoughts Flesym . I never really worked in a big team-project as I said, nor even close to a real costumer. I do, however, see the importance of UML especially when working close to costumers who knows "niente" about programming.

I wonder how big Open-source projects are designed though. Something like Firefox, for example. What I mean is, did a good documentation was written for it before the actual code? Indeed, big guns as Eclipse must have a huge documentation (is IBM behind it isn't it?), but I wonder how things work more on the "real" open-source level using a CVS/SVN repository

P.S: I've to apologize for my English. I've not used English (or posted much here) for a while and I can't believe the amount of errors I had in my above post. It will be better soon, hopefully, hihi ^_^.