Which article should I use when referring to a program function's argument?

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.

Petr Pudlák

Posted 2013-03-17T15:28:17.920

Reputation: 425

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. – snailplane – 2013-03-17T16:08:43.537

You 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. i = i + 1 //add one to i)

– Hellion – 2013-03-17T16:13:43.853

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

Answers

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.

ADDED:
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.

StoneyB on hiatus

Posted 2013-03-17T15:28:17.920

Reputation: 176 469

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) {

Trish Rempel

Posted 2013-03-17T15:28:17.920

Reputation: 1 524