Pcl: [docs] Ordering of header includes

[divmadan]

Description

There is no documentation available to refer, regarding the ordering of includes to be followed throughout the source.

Context

While running clang-format, it rearranges header includes:

#include <pcl/common/eigen.h>             #include <ctime>
#include <crime>                ->    #include <pcl/common/eigen.h> 
#include <pcl/tracking/tracker.h>     #include <pcl/tracking/tracker.h> 

Blame from my PR

While searching for documentation regarding the ordering, I found out there isn't one.

Expected behaviour

• A set pattern to be enforced throughout the source, with exceptions, if any, documented.
• No rearrangement while formatting code.

Describe the solution you'd like

1. Documentation of the order of includes, if we have one. Else, adoption of one.
   Example: https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes
2. Addition of a style option in our .clang-format file, to prevent rearranging.
   
   
   
   • Set SortIncludes (bool) as false.
   
   
   • Alternatively, explore options like IncludeBlocks (IncludeBlocksStyle) and IncludeCategories (std::vector<IncludeCategory>).
   
   
   • Clang format 10 documentation
   
   
3. Enforcing the order throughout the source (Discussion needed).

---

Initially suggested by @kunaltyagi in https://github.com/PointCloudLibrary/pcl/pull/3814#discussion_r406749664

[aPonza]

This was discussed previously, off the top of my head I can remember https://github.com/PointCloudLibrary/pcl/pull/3654#issuecomment-586961703 where there seemed to be an agreement on "library -> 3rd party -> std".

I'd argue it'd be nice to have the first include be the "main" include for the file: see https://github.com/PointCloudLibrary/pcl/pull/3898#issuecomment-611668454 where I mentioned clang-format's IncludeIsMainSourceRegex which would leave the first include of a file alone as the main one (i.e. the .h declaring the .hpp or the .cpp stuff to define).

EDIT: an example:

file: module/src/foo.cpp

/** license */

#include <pcl/module/foo.h>

#include <pcl/memory.h>
#include <pcl/point_cloud.h>
#include <pcl/point_types.h>
#include <pcl/common/transform.h>
#include <pcl/io/openni_grabber.h>
#include <pcl/io/pcd_grabber.h>
#include <pcl/visualization/cloud_viewer.h>
#include <pcl/visualization/pcl_visualizer.h>
#include <pcl/visualization/point_cloud_handlers.h>

#include <boost/filesystem.hpp>

#include <Eigen/Core>
#include <Eigen/Geometry>

#include <opencv2/opencv.hpp>
#include <opencv2/gpu/gpu.hpp>

#include <functional>
#include <iostream>
#include <mutex>

[SunBlack]

Just to mention: I'm currently working on the adjustment to .clang-format (I don't see any PR currently for it, so just mention that not multiple PRs will be started ;-) )

[SunBlack]

PR is opened here #3909.

[kunaltyagi]

@divmadan @SunBlack Any new updates for doc module?

[divmadan]

If @SunBlack 's busy, I'll do it.

[divmadan]

To be added to the 2. Indentation and Formatting in the PCL style guide, right?