-1

Are there any small projects that illustrate best practices of C++? It would be really great if one can learn a lot from one simple and fully commented project, rather than reading materials that show best practices with many unrelated snippets.

As an example, one of the header file of the project could look something like this:

#pragma once // Use 'pragma once' if your compiler supports it. Faster build time than using include guard. More explanation...

#ifndef MYHEADER_H // Traditional include guard, for compilers that do not support #pragma once

class Apple; // use forward declaration whenever possible to reduce build time
fxam
  • 3,874
  • 1
  • 22
  • 32
  • 2
    Just so you know, `#pragma once` is non-standard, and it does not provide faster build times. Compilers are smart enough to recognize include guards. It is also very problematic and could give you a very big headache, for example, when the same content could be possibly included from two different files etc. –  Jan 05 '12 at 14:42
  • 5
    If such a project existed, and it did contain comments similar to what you posted, I wouldn't recommend it. You should probably buy (and read) "Effective C++" if you are looking for best practices. – fredoverflow Jan 05 '12 at 14:44
  • I believe I heard that some versions of the MS compiler don't properly recognize/optimize normal include guards. – Mark B Jan 05 '12 at 14:45
  • 3
    It would be *really* tiring if every include guard was commented. There's a motto "Write code, not comments", that encourages you to write idiomatic, self-descriptive code rather than overload your program with comments. It's good advice. – Kerrek SB Jan 05 '12 at 14:46
  • And the forward declarations, I don't understand why that is a good idea. Personally I always try to order my declarations in such a way that forward ones aren't needed, except when absolutely necessary. – Mr Lister Jan 05 '12 at 14:50
  • 1
    @Mr Lister If you work in medium+ sized projects forward declarations can save hours of compile time over a week. And to continue Kerrek SB's note, comments should typically be strategically placed to describe an algorithm, pre/post conditions, important notes about an interface. I also use them in the rare piece of code that has to be ordered in a certain way, or when there's an obscure bug that was fixed and should be documented. – Mark B Jan 05 '12 at 14:52
  • @VladLazarenko Not sure I understand why you say #pragma once could give you a headache. Could you give an example of a situation where #pragma once causes problems that #ifndef wouldn't cause? – Mr Lister Jan 05 '12 at 14:53
  • @MrLister: You should minimise dependencies between headers and TUs. – Cat Plus Plus Jan 05 '12 at 14:54
  • @KerrekSB: The advice holds for "real-world" projects, but for teaching purposes, you sometimes want/need to comment most of the code to explain why you did certain things in a certain way. The code I give to my students is crammed with comments explaining best practices, alternative solutions, etc. – Luc Touraille Jan 05 '12 at 14:54
  • @Mr Lister If your compiler is running in a strict warning mode the `pragma`s could result in diagnostics I believe. The normal include guards will never result in diagnostics. – Mark B Jan 05 '12 at 14:55
  • 1
    @MrLister: Yes, when the same content is stored in two different files (from compiler's point of view). There even was a bug with symlinks in `gcc` some time ago that was fixed later. Why do you think this crap is not in standard? It is weak :) –  Jan 05 '12 at 14:55
  • For teaching purpose I'd suggest one of the books from http://stackoverflow.com/questions/388242/the-definitive-c-book-guide-and-list (obligatory link to the book list). – Mark B Jan 05 '12 at 14:56

1 Answers1

4

I'm pretty convinced such a project doesn't exist, and if it existed I probably wouldn't recommend it over a good book. There are several problems with your premise:

  • Whole books have been written about the topic of best practices in c++, so I'd be very doubtful about any small project illustrating any reasonable number of those. Note that this doesn't mean that books can't have coherent examples instead of unrelated ones, but it's typically still picked from a bigger codebase

  • Best practices are kind of pointless without a thorough explanation, why they are sensible. For many best practices that explanation isn't exactly short enough to fit in your typical code comment (having 20 lines of comment between each line of code (slight exaggeration, but probably not by that much) doesn't make a project very readable).

  • Many best practices in c++ (or in programming in general, but it's particularly pronounced in c++) are controversial, so it is sometimes a good idea to show the different ways to solve a particular problem (and say why one is better), which is easily done implementing the same example several times in different ways in a book/tutorial, but that's not sensible in a project.

So concluding I would rather recommend reading a good book about C++ practices. So pick a book from here. I'd consider Scott Meyers Effective C++ (and Effective STL and possibly More Effective C++ once you are finished) for best practices, but some others could do the job too.

Community
  • 1
  • 1
Grizzly
  • 19,595
  • 4
  • 60
  • 78