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 the given number.


This function squares a given 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 given might have some semantic interference from the phrase a given, as in "On a given day, I might be anywhere from Alaska to Nebraska". Using the word the avoids this interference.
    – user230
    Commented Mar 17, 2013 at 16:08
  • You should also go over to programmers.stackexchange.com and read the wealth of commentary there about why commenting on the obvious is a bad thing. (E.g. i = i + 1 //add one to i)
    – Hellion
    Commented Mar 17, 2013 at 16:13
  • The words "this function" are redundant, given that the comment is likely to be right next to the top of the function. Commented Mar 17, 2013 at 16:38
  • 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
    Commented Mar 17, 2013 at 16:45

2 Answers 2


Either is acceptable, since what is in play is "whatever number is given", which is indefinite in the code but definite at run time.

But presumably your code gives a name to your 'given number'; why not employ that? That is,

function Sqr(Arg) \\ this function returns the square of Arg mutatis mutandis for whatever syntax your language employs.

As snailplane points out, it is important to avoid any possibility of ambiguity, following the Writer's Prime Rule: “Anything which can be misunderstood will be.” So it's probably a good general practise never to refer to any program entity by such a periphrasis or circumlocution as given number: refer to it by name.


As mentioned in the comments, the best documentation is well-written code. However, I will assume that you are documenting a function that needs a little bit more explanation.

As a programmer, typically, I would describe the parameter by name, or at least by its type, and if it is by type, I would use "a" instead of "the" because "a" can be any value of that type, while "the" sounds like it is describing a specific value.

Example comment referencing the parameter type:

// Returns the square of an integer
function int square(int value)

Example comment referencing the parameter names:

// Returns width multiplied by height
function int area(int width, int height) {

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .