5

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.

4
  • 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
    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
    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. 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
    Mar 17, 2013 at 16:45

2 Answers 2

3

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.

2

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 .