I'm quite stupid/forgetful, so when I write code I try to do it such that some unexpected 3rd party (i.e. me in about 3 weeks time) can read through and figure out what's going on. This generally means I include a sections both at the beginning of the code and in line which explain what I'm actually trying to achieve, broadly speaking. It's amazing how much easier it is to read complex technical code if you understand what the goal is.
Comments which describe the code are much less useful than a commentary regarding the code's objectives, in my opinion.
Comments
I'm quite stupid/forgetful, so when I write code I try to do it such that some unexpected 3rd party (i.e. me in about 3 weeks time) can read through and figure out what's going on. This generally means I include a sections both at the beginning of the code and in line which explain what I'm actually trying to achieve, broadly speaking. It's amazing how much easier it is to read complex technical code if you understand what the goal is.
Comments which describe the code are much less useful than a commentary regarding the code's objectives, in my opinion.
Yes, with code documentation write "why" not "how."
I like to put it as "what for" not "what."