properly use readlink() + a bit of code documentation