What are the parts that a good C++ project should contain? (Docs, Makefile, Tests etc...)

Question

Hi there ,

i am writing my bachelor thesis and there is some C++ code attached to it. I want to have a nice clean Project.

So what should be in it ?

I think :

• Documentation in html ( generated with Doxygen)
• README File
• Makefile ( which make ? CMake ? )
• Unit-Tests ( which unit test framework? )
• Copyright Text ?
• ...

Did i miss something ?

Answer 1

Simplify the list:

• Documentation in a place and form that can easily be found and read, including
  • instructions on how to build it;
  • instructions on how to use it.
• Some sort of confidence testing ("I compiled it, but does it work?").

Whether the docs are HTML, plain text or in-source comments; whether there's a Makefile or a batch script or a copy & paste one-liner in the README.txt; whether you've got a full-blown unit testsuite or a "golden file" test:

It doesn't matter really.

The important thing is that you can build it, test it, and use it as easily as possible.

---

Adding personal opinion:

KISS. (Keep it short and simple.)

Go with simple source comments for small projects, and only start the Doxygen stuff when you grow beyond a certain point. Make sure your documentation framework doesn't make it harder to find things via full-text search, because in my experience, that's what people end up doing unless you wrote your docs really well.

Go with a simple Makefile and use more sophisticated stuff (like CMake, automake etc.) only when it becomes necessary. For small projects, the amount of "metadata" in comparison to "real" source files can become ridiculous.

You can sink quite some time and energy in this "supporting cast", which - in the beginning of a project - should be put into the project itself. Build system, documentation etc. can grow as necessary, but the project architecture itself is a bitch to refactor once it's been released. That's where your primary focus should be.