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

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

or

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

4

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

3

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