diff --git a/src/beat_track.c b/src/beat_track.c
index 7708e4a..8db31e9 100644
--- a/src/beat_track.c
+++ b/src/beat_track.c
@@ -1,8 +1,9 @@
 #include "beat_track.h"
 #include "settings.h"
 
-#include <stdio.h>
-
+/**
+ * initialize circular buffer to [capacity] items
+ */
 void cb_init(cebuffer *cb, const int capacity)
 {
     cb->buffer = (energy_t*)malloc(capacity*sizeof(energy_t));
@@ -13,6 +14,9 @@
     cb->tail = 0;
 }
 
+/**
+ * free and reset buffer
+ */
 void cb_free(cebuffer *cb)
 {
     free(cb->buffer);
@@ -21,7 +25,9 @@
     cb->tail = 0;
 }
 
-// insert, deleting oldest element if needed
+/**
+ * insert, replacing oldest element if needed
+ */
 void cb_push_back(cebuffer *cb, const energy_t item)
 {
     // insert on head+1
@@ -38,6 +44,9 @@
     }
 }
 
+/**
+ * compute the average energy in the buffer
+ */
 double cb_avg(cebuffer *cb)
 {
     double avg = 0;
@@ -56,6 +65,9 @@
     return avg / cnt;
 }
 
+/**
+ * compute energy variance in the buffer
+ */
 double cb_variance(cebuffer *cb)
 {
     double variance = 0;
@@ -71,11 +83,17 @@
             variance += pow(diff, 2);
         }
     }
-    fprintf(stderr, "variance TOTAL: %f\n", variance / cb->count);
     return variance / cb->count;
 }
 
-bool cb_beat(cebuffer *cb, const energy_t item, energy_t* energyThreshold)
+/**
+ * Beat detection entry point (simple/faster algorithm: no variance)
+ * - threshold: compute avg of values, multiply it by a scaling factor
+ * - item > thresold -> beat
+ * - item <= threshold -> no beat
+ * store thresold value to re-use it (TODO improve algorithm)
+ */
+bool cb_beat(cebuffer *cb, const energy_t current, energy_t* energyThreshold)
 {
     bool beat = false;
 
@@ -83,7 +101,7 @@
     double mult = (double)17/16;
     double et = mult*cb_avg(cb);
 
-    if(item > et) {
+    if(current > et) {
         beat = true;
     }
 
diff --git a/src/beat_track.h b/src/beat_track.h
index f6a58a5..6c3a058 100644
--- a/src/beat_track.h
+++ b/src/beat_track.h
@@ -7,7 +7,13 @@
 
 typedef unsigned int energy_t;
 
-// circular energy buffer
+/**
+ * circular energy buffer
+ * beat tracking is performed by aggregating
+ * values in the buffer and comparing them with the
+ * current sampled energy
+ * - multiple ways (avg, variance) => beat_track.c
+ */
 typedef struct cebuffer
 {
     energy_t* buffer;     // data buffer
@@ -17,7 +23,7 @@
     int tail;       // pointer to tail
 } cebuffer;
 
-void cb_init(cebuffer *cb, int capacity);
+void cb_init(cebuffer *cb, const int capacity);
 void cb_free(cebuffer *cb);
 void cb_push_back(cebuffer *cb, const energy_t item);
 bool cb_beat(cebuffer *cb, const energy_t item, energy_t* energyThreshold);
diff --git a/src/fft.c b/src/fft.c
index e2fe23a..1417a7f 100644
--- a/src/fft.c
+++ b/src/fft.c
@@ -1,9 +1,15 @@
 #include "fft.h"
 #include "settings.h"
 
-/* if flag is EVEN (0), it takes only the even elements
- * otherwise if flag is ODD (1) it takes only the odd ones
- */
+/**
+ * FFT algorithm
+*/
+
+/**
+ * split an array
+ * - if flag is EVEN (0), take only even elements
+ * - else if flag is ODD (1) it takes only the odd ones
+*/
 cplx *split_array(cplx *a, const int len, const int flag)
 {
 	int i, cnt = 0;
@@ -18,17 +24,18 @@
 	return ret;
 }
 
-/* recursively compute the fft on an array of complex numbers
+/**
+ * recursively compute the fft on an array of complex numbers
  * splitting the array in two parts each recursion
- */
+*/
 cplx *_fast_ft(cplx *compArray, const int len)
 {
   cplx omegaN, omega;
   cplx *evenA, *oddA, *transformedA;
   int i;
 
-  /*termination*/
-  if(len == 1){
+  // recursive termination
+  if(len == 1) {
     return compArray;
   }
 
@@ -51,17 +58,11 @@
   return transformedA;
 }
 
-void
-print_components(cplx *a, const int len)
-{
-  int i;
-  for(i=0; i<len; i++){
-    /*creal and cimag extract the real and imaginary parts of a[i]*/
-    fprintf(stdout, "%g, %g\n", creal(a[i]), cimag(a[i])); 
-  }
-  fprintf(stdout, "\n");
-}
-
+/**
+ * compute the amplitude of each fft component (cplx)
+ * - amplitude = sqrt((real**2)/nc + (img**2)/nc)
+ * - nc: number of components (samples)
+*/
 unsigned int
 amplitude(cplx c, const unsigned int n)
 {
@@ -71,6 +72,13 @@
   return round(20*log10(sq)); // dB scale
 }
 
+/**
+ * FFT algorithm entry point
+ * receives an input len, a raw buffer and an output buffer
+ * - computes the FFT of the raw buffer as a complex array
+ * - computes the amplitude of the complex FFT components
+ * - stores the result in the output buffer
+*/
 void
 fast_fft(const int inLen, uint16_t *sig, unsigned int *fftSig)
 {
@@ -96,23 +104,47 @@
   free(outputComponents);
 }
 
+
+/**
+ * ===============================================
+ * Compute logarithmic avg of fft amplitude buffer
+ * ===============================================
+*/
+
+/**
+ * upper frequency bound for current bin
+*/
 const double upperbound(const double bfreq, const double x)
 {
     return bfreq*pow(2, 1/(2*x));
 }
 
+/**
+ * lower frequency bound for current bin
+*/
 const double lowerbound(const double bfreq, const double x)
 {
     return bfreq / pow(2, 1/(2*x));
 }
 
+/**
+ * central (base) frequency of next bin 
+*/
 const double next_bfreq(const double bfreq, const double x)
 {
     return bfreq*pow(2, 1/x);
 }
 
 
-// average fftBuf using a logarithmic scale for bins, to respect octaves
+/**
+ * Average algorithm:
+ * - while (!bin limit reached):
+ * --- compute bin upper and lower bound from bfreq
+ * --- sum each fftBuf[i] for i in (lower, upper)
+ * --- divide by (upper-lower) to get the avg
+ * --- if more than one fftAvg per bin, replicate on FOCUS
+ * --- compute next bfreq
+ */
 void
 average_signal(unsigned int *fftBuf, const int inLen, const int max, const double bf, const int oratio, unsigned int* fftAvg)
 {
@@ -156,7 +188,13 @@
     }
 }
 
-// compute the average energy of a sample array (in amplitude form)
+/**
+ * ===================================================
+ * Energy computation for beat tracking (beat_track.h)
+ * ===================================================
+ * Energy = average of the square of the amplitude
+ * stored in fftBuf
+*/
 void avgEnergy(unsigned int* fftBuf, const int inLen, unsigned int* energyBuf)
 {
     unsigned int i;