Includes Reorganization

[Hoikas]

While working on #383 to make our cmake more target-based and cleanup the dependency linkage, I've found lots of issues with our includes throughout the codebase. I have most commonly encountered the following issues:

• including headers that are unused
• including headers when a forward declaration is sufficient
• leaving out includes for required types, depending on another header to include its declaration
• seemingly random include ordering
• including the same header twice in the same file (see previous item)

The results of these issues are longer compile times, #include side-effects, and difficulty in understanding a target's dependencies. Among the side effects, some headers seem to (still) bring in windows.h, which defines many things that conflict with Plasma's code (eg DrawText and GetObject) -- this can break in subtle ways if includes are reorganized.

With that in mind, I would like to propose the following rules for includes:

• Includes must come immediately after the license block. No headers should be included after the first non-include line of code, except in the case of preprocessor tricks (inlined files)
• You must directly include what you use.
  • See also: https://include-what-you-use.org/
• Headers should avoid including other headers except when a forward-declaration is insufficient.
• Headers should not define the body of virtual functions.
• No header should include hsWindows.h or windows.h
• No header should include a Pch.h (dedicated precompiled header)

Includes should be arranged in blocks ordered as demonstrated:

#include "MyCppFileHeader.h"

#include "hsCoreLibHeader.h"
#include "plgDispatch.h"
#include "pnNucleusIncHeader.h"

#include "pnSomeNukeLib/pnAwesome.h"
#include "pnUUID/pnUUID.h"

#include "plInterp/hsInterp.h"
#include "plVault/plVault.h"

#include "pfCamera/pfVirtualCamNeu.h"

Or, in text:

• Always include the cpp file's header first
• Any core/nucleus inc header
• NucleusLib
• PubUtilLib
• FeatureLib

Within each block, all includes should be alphabetized without considering any prefixes. This will enable casual perusal. Any 3rd party or STL includes may form additional blocks following these rules. These blocks must come after the cpp file's include.

Further, when #383 is complete, I believe we should reorganize all headers into the following structure:

Sources
    Plasma
        FeatureLib
            pfPatcher
                pfPatcherWorker.cpp
                pfPatcher.cpp
Headers
    Plasma
        FeatureLib
            pfPatcher <--- Target include INTERFACE
                pfPatcher <- Target include PRIVATE
                    pfPatcher.h
                    pfManifest.h
                Private <---- Target include PRIVATE (if needed)
                    pfPatcherPrivateImpl.h

This will ensure that any target that wants to consume pfPatcher must link against pfPatcher to even see its headers. It would continue to allow targets to include their own headers directly by name and for other targets to include things by <target>/<file>. Further, it allows for stronger (but not maximum) enforcement of what is a private header... For example, only the plPhysX target should be including the file plPhysXAPI.h, which includes actual PhysX headers.

[Hoikas]

After some discussion on IRC related to the source tree structure, I'm changing my recommended header organization to look like this:

Sources
    Plasma
        FeatureLib
            pfPatcher <------ Target include PRIVATE
                pfPatcherWorker.cpp
                pfPatcherPrivateImpl.h
                pfPatcher.cpp
                Includes <--- Target include PUBLIC
                    pfPatcher
                        pfPatcher.h

This should make navigating to a header file require less directory backtracking.