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.

  • 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. – snailcar Mar 17 '13 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 '13 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. – Steve Melnikoff Mar 17 '13 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 Pudlák Mar 17 '13 at 16:45
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.

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.