Guideline in library creation

Question

According to this example, creation of an Arduino library is quite understandable.

But a few things I would like ask (mostly regarding to what to be defined where) when a library is not that simple:

1. Where to put additional libraries (such as <Wifi.h>) in .h or .cpp, since it works when defined in each one of them?

2. What is the purpose of defining variables in the :private section? Since they can be defined inside constructor, and as far as I know/tested, it works as well.

3. In a .cpp file, does it matter when instances or variables are defined outside a class (at the beginning of code ), since again, it works the same?

Answer 1

Where to put additional libraries (such as ) in .h or .cpp, since it works when defined in each one of them?

It doesn't really matter as long as the parts of your library that need to see the headers can see them. Personally I put all headers in the master .h file and then that gets included in the .cpp file(s). It just keeps it all in one place and is easier to manage.

What is the purpose of defining variables in the :private section? Since they can be defined inside constructor, and as far as I know/tested, it works as well.

You need to understand "scope". Defining a variable inside the constructor means that it's only available within that constructor. This is "local" scope. Defining the variable in the class, within the "private" section makes that variable available to every function within the class. Putting it in "public" makes it available to anyone anywhere.

In a .cpp file, does it matter when instances or variables are defined outside a class (at the beginning of code ), since again, it works the same?

Again this is a matter of "scope". A variable declared outside the class is in "global" scope. There is only one copy of each of these variables, and all instances of the class share the same physical variable. It is the same as declaring a class variable as "static" - it makes it common to all instances of the class. If the data you need to store is specific to a class instance (which most of the time it is), you do not want to use global variables. In general it's bad form using global variables if you don't have to.

Incidentally, you may see variables defined both in the class and at the top of the CPP file. This is a special case where you have static variables in your class, which don't have any storage space allocated to them (normally a variable has its storage space allocated when you create an instance of the class, but that doesn't happen with static variables for obvious reasons), so you have to manually provide the storage space with a separate entry in the CPP file.

Answer 2

1. Where to put additional libraries (such as <Wifi.h>) in .h or .cpp, since it works when defined in each one of them?

Any library can reference any other library. So including another library in your library is the same as including in the sketch. They should be on standard locations.

Include the other libraries .h in the file where you need it. If you use something from the other library in your .h, include it there. If you need it only in .cpp include it there.

2. What is the purpose of defining variables in the :private section? Since they can be defined inside constructor, and as far as I know/tested, it works as well.

With declaring a class member as private, the author of the class tells: don't use it, it is for internal use and can change in future versions.

3. In a .cpp file, does it matter when instances or variables are defined outside a class (at the beginning of code ), since again, it works the same?

If the variable is not a member of the class, then if you create two instances of the class they will share the variable. A variable in constructor is restricted to the constructor's scope.

Answer 3

Regarding 1: prefer to add it in the sketch/.cpp file only. If this is not possible (because you need the class to be known in the header file, only than add it in the header.

Reason: a header file is typically included by many other files and adding an include results in more coupled code, making later maintenance more difficult.

Regarding 2/3: See also the somewhat related answer of me in why-to-store-a-function-parameter-value-in-a-class-private-variable.