Correct / Preferred syntax for adding Include Files

Using Arduino Programming Questions
#1

Probably a newbie question, but …

I have noticed when reviewing other peoples sketches, that different Sketches seem to use two different methods to add Include files to a Sketch?

i.e.

#include <SoftwareSerial.h>

//or

#include "SoftwareSerial.h"

Is there any specific reason for using either of the options as they both compile, or are they effectively interpreted exactly the same way by the compiler, what is the preferred / best option and why ??

I have noticed that when < > are used, then the name of the include file is highlighted in red by the IDE so it obviously recognises that they are different.

#2

have a look at C header file #Include directive

#3

fimez:
Is there any specific reason for using either of the options as they both compile, or are they effectively interpreted exactly the same way by the compiler, what is the preferred / best option and why ??

I was recently requested to add some documentation about this to the #include page of the Arduino Language reference. This is what I have proposed:

Syntax

#include <LibraryFile.h>

#include “LocalFile.h”




**Parameters**
**LibraryFile.h**: when the angle brackets syntax is used, the libraries paths will be searched for the file. +
**LocalFile.h**: When the double quotes syntax is used, the folder of the file using the `#include` directive will be searched for the specified file, then the libraries paths if it was not found in the local path. Use this syntax for header files in the sketch's folder.

Within the context of the rest of the reference page, does that explanation make it clear to you? If not, please let me know what you find to be confusing or if you have any ideas for improvement.

fimez:
I have noticed that when < > are used, then the name of the include file is highlighted in red by the IDE so it obviously recognises that they are different.

Yes, but not in any way specific to #include. Library authors may define keywords of the library. The Arduino IDE highlights occurrences of all keywords defined by all installed libraries whenever they occur in the sketch code. However, it does not do this for strings. The quoted “SoftwareSerial.h” is a string, which the version surrouded by angle brackets <SoftwareSerial.h> is not.

In general, this highlighting of the header filename is purely a side effect of the common practice of the class name being the same as the header filename that contains its declaration. The library author’s intent was for the class name to be a keyword, not the filename. You will find that the header filenames of libraries aren’t always highlighted as keywords by the IDE, so don’t place much importance on the colors of things in the Arduino IDE. What’s important is what the compiler thinks of the code, and the compiler doesn’t know anything about the arbitrary keywords definition system. That’s purely cosmetic.

#4

horace and pert, thank you so much to both of you for your explanations and pointers to more reference materials.

It probably makes more sense to use <> in most instances when using include files as unless you have written them specifically yourself or have modified an original Library file they are predominantly going to be located in the system directory, but I understand now the difference between the syntax.

It’s good that whichever you use the header file will probably be found anyway if it’s not in the Local directory (as long as it exists obviously) and this also saves having to copy standard Library files all over the place.

Regards,

Fimez.

#5

My advice is always to use the most appropriate syntax, even if either one would work.

One reason is because it better conveys the intent of that code. For example, this syntax:

#include "SoftwareSerial.h"

when using the SoftwareSerial library in your sketch will work, but it causes the sketch folder to unnecessarily be checked for the file. Someone reading this line who knows C++ but is not familiar with the code might wonder "is there a missing file named SoftwareSerial.h that is supposed to be in the sketch folder"?

Library authors often use the double quotes and angle brackets syntax arbitrarily. With a standard library installation, either syntax will work both for files inside the library as well as external files. However, sometimes it's useful to bundle a library with a sketch so that the sketch can be a self-contained package. When you do this with a library that uses angle braces for local files, it no longer works because the library is no longer installed in the libraries folder that is searched with angle braces. If the library author had used the correct double quotes syntax for local files, this would not be a problem.

#6

When you start splitting up your code, you have the option to either use multiple ino files or putting parts of your code in .h and .cpp files.

That’s where the double quotes come in handy.

It will also allow you to override a standard library with your own version for a specific sketch…

#7