Before every function definition, and occasionally for bits of code within functions, I throw a line of text such as sswift wrote in that last comment. Just seeing a line of code doesn't tell me what it does (in the high-level sense); for that I need some actual english.
I stick to a pretty strict convention with my functions. They all look like so:
This way it's easy for me to visually focus on one function and ignore what's around it. Saying it's strict is misleading though; it's total habit so I never think about it or expend any extra effort. Also, I keep an empty example function at the bottom of my code so that I can just copy/paste it whenever I'm placing a new function, rather than having to write out that formatting every time.
I like that example. I believe I will steal it. A lot of people have difficulty grasping the notions of low-level and high-level.
I stick to a pretty strict convention with my functions. They all look like so:
;--------------------------------------- ;description of what the function does Function Name() code End Function ;---------------------------------------
This way it's easy for me to visually focus on one function and ignore what's around it. Saying it's strict is misleading though; it's total habit so I never think about it or expend any extra effort. Also, I keep an empty example function at the bottom of my code so that I can just copy/paste it whenever I'm placing a new function, rather than having to write out that formatting every time.
Line-by-line, there's no point in having comments. But the big picture, that's where commenting is usually needed. You may be able to figure out that such-and-such code sorts out a list, for example, but... why are we sorting it to begin with? Those kinds of comments are what's needed.
I like that example. I believe I will steal it. A lot of people have difficulty grasping the notions of low-level and high-level.