More comment added

basic/mean_modular.cpp

+// An example of a modular procedure
 #include <iostream>
 
+// The namespace, a module that stores any kind of entity
 namespace mtools{
+// An user defined type having just public data and no user defined operation
   struct avars{
     int ncount;
     int rsum;
     double amean;
   };
 
+// A module implementing a procedure, that is a function
+// This function operates on an object of the above user
+// defined type and calculates the average
   void calcave(avars & a){
     double stemp{static_cast<double>(a.rsum)};
     double ntemp{static_cast<double>(a.ncount)};
     a.amean=stemp/ntemp;
   }
 
+// A function updating the state of an object of the above
+// user defined type, incrementing the running sum and the number of counts
   void updateave(avars & a, int d){
     a.rsum+=d;
     a.ncount++;
   }
-
+// A function that just print the value of the mean, stored into an object
+// of the above defined type
   void printave(const avars & a){
     std::cout <<"Arithmetic mean: " << a.amean<< std::endl;
   }
 }
 
+// Every C++ program must start executing a function called main.
 int main(){
-
+// Create object of type defined in the module namespace mtools
   mtools::avars a{};
   int indata{0};
   std::cout <<"Enter values [Ctrl-D to finish]: " <<std::endl;
 
+// The procedure is now less bound to the chosen algorithm
+// but it scale, thanks to the modularization.
   while(std::cin>>indata){
     mtools::updateave(a,indata);
     mtools::calcave(a);

basic/mean_procedure.cpp

-#include <iostream>
+// An example of procedural programming
 
+#include <iostream> // For std::cout and std::cin declarations
+
+// All C++ program must start with a function called main()
 int main(){
 
+// Definition of variables
   int ncount{0},rsum{0},indata{0};
   double amean{0.};
 
+// A printout
   std::cout <<"Enter values [Ctrl-D to finish]: " <<std::endl;
+// The procedure
+// First ask for data and read it
   while(std::cin>>indata){
     rsum+=indata; // rsum=rsum+indata;
     ncount++; // ncount=ncount+1;
+    // Convert values into the right types
     double stemp=static_cast<double>(rsum);
     double ntemp=static_cast<double>(ncount);
+    // Do the calculation
     amean=(ntemp!=0)?stemp/ntemp:0.;
   }
-
+// Print the result
   std::cout <<"Arithmetic mean: " << amean<< std::endl;
   return 0;
 }

basic/mean_procedure_auto.cpp

-#include <iostream>
+// An example of procedural programming using the type auto deduction
 
+#include <iostream> // For std::cout and std::cin declarations
+
+// All C++ program must start with a function called main()
 int main(){
 
-  auto ncount=0,rsum=0,indata=0;
-  auto amean=0.;
-  decltype(rsum/ncount) truncmean;
+// Definition of variables
+  auto ncount{0},rsum{0},indata{0};
+  auto amean{0.};
 
-  std::cout <<"Enter values [Ctrl-D to finish]: \n" ;
+// A printout
+  std::cout <<"Enter values [Ctrl-D to finish]: " <<std::endl;
+// The procedure
+// First ask for data and read it
   while(std::cin>>indata){
     rsum+=indata; // rsum=rsum+indata;
     ncount++; // ncount=ncount+1;
+    // Convert values into the right types
     auto stemp=static_cast<double>(rsum);
     auto ntemp=static_cast<double>(ncount);
+    // Do the calculation
     amean=(ntemp!=0)?stemp/ntemp:0.;
-    truncmean=(ntemp!=0)?rsum/ncount:0;
   }
-
-  std::cout <<"Arithmetic mean: " << amean<< '\n';
-  std::cout <<"Rounded to int mean: " << truncmean<< std::endl;
+// Print the result
+  std::cout <<"Arithmetic mean: " << amean<< std::endl;
   return 0;
 }
+

basic/mean_userdefined.cpp

+// An example of programming using user defined types
 #include <iostream>
 
+// Here is the type definition, that is a declaration
+// containing the type data layout and the operations
+// needed to use the type in the correct way.
+// The type is created using a class, that is a type that
+// implement a separation between a public part, what every
+// user can use, and a private part, what can be used only
+// by object of the type itself.
 class ave{
 public:
-  ave(): ncount_(0), rsum_(0), amean_(0) {};
-
+// Here the modules, functions, needed to create an object in memory
+// And operate on the data layout
   ave & operator+=(int d){
     rsum_+=d;
     ncount_++;
@@ -15,25 +23,31 @@ public:
 
   double get_ave() const { return amean_;}
 
-
 private:
-    int ncount_;
-    int rsum_;
-    double amean_;
-
+// Here the list of data needed to describe
+// the type.
+    int ncount_{0};
+    int rsum_{0};
+    double amean_{0.};
 };
 
-
+// Every C++ program must start executing a function called main.
 int main(){
-
+// User's types have the same support of the base types
+// Create an object with a state, i.e. data layout, and
+// a behavior, i.e. the code needed to manage the data layout,
+// connected somehow in memory.
   ave a;
   int indata{0};
   std::cout <<"Enter values [Ctrl-D to finish]: " <<std::endl;
 
+// The object oriented programming semantic is implemented in C++ using
+// operators, that is symbols that represent an operation. Here std::cin and a
+// are the "object"s to operate on ...
   while(std::cin>>indata){
     a+=indata;
   }
-
+// ... here the std::cout is the "object" to "use"
   std::cout << "Average: " << a.get_ave() << std::endl;
   return 0;
 }