Cómo documentar las decisiones de un proceso

// Leo el documento
    $pages = fopen($original);
// Recorro las paginas una a una
foreach($pages as $p){
    // Sumo al count para tener el numero de pagina
        $count++;      
    // Reemplazo la almohadilla por el numero del contador
        $pagenum = str_replace('#',$count,$separador);
    // Coloco el nombre del fichero para que sea con el PREFIJO del contador + nombre del fichero original
        $filename = $pagenum . $original
}

/*
    PROYECTO
    1. Leo el documento
    2. Recorro las paginas
    3. Cuento cada una
    4. Reemplazo el numero
    5. Y guardo el nuevo documento con su numero de pagina
*/