4

Let's say I'm documenting a library function that (for example) accepts a number and returns the number squared. Should I write

This function squares

thegiven number.

or

This function squares

agiven number?

At the time of writing the sentence, there is no particular number we'd be referring to. But at the time the function is executed, there is a concrete number that is being squared.

Your use of

givenmight have some semantic interference from the phrasea given, as in "On a given day, I might be anywhere from Alaska to Nebraska". Using the wordtheavoids this interference. – snailplane – 2013-03-17T16:08:43.537You should also go over to http://programmers.stackexchange.com and read the wealth of commentary there about why commenting on the obvious is a bad thing. (E.g.

– Hellion – 2013-03-17T16:13:43.853`i = i + 1 //add one to i`

)The words "this function" are redundant, given that the comment is likely to be right next to the top of the function. – Steve Melnikoff – 2013-03-17T16:38:06.907

2@Hellion In my case, the behavior of the function is nontrivial. I just chose this simple example so that the question isn't obscured by technical details. – Petr Pudlák – 2013-03-17T16:45:41.987