13

In this piece of documentation, many examples of Java array declarations are given. They follow the basic scheme of arr1[], arr2[], etc.

It's not necessarily clear that arr is a shortened form of array, and this information may help a new Java programmer learn about arrays. What's the best way to include that? Renaming every array in the post to array1[], array2[], respectively, etc.? Commenting after the first occurrence of arr1[] and that's it? Or leave it the way it is, as it's obvious enough?

Similarly in Node.js, there's a line of code used often in tutorials about Node.js servers:

function handler(req, res) {

Similar to the above, req refers to a request, and res to the response, or something like that. While technically the arguments could be renamed, it seems standard to call them that in almost any Node.js tutorial you can find. Would it therefore make sense to comment what these three character nicknames are referring to, in situations like this, at the first mention?

4
  • 2
    "It's not necessarily clear that arr is a shortened form of array" Does it matter? It's a variable name, one which has no real semantic meaning (since the example is too short for that). It doesn't matter of the reader knows that arr1 is short for "array 1". All they need to know is that arr1 is a variable with that name, which is distinct from arr2. Jul 24, 2016 at 14:09
  • 7
    @NicolBolas Then why not use a, b, c, etc., for the variable names? It'd lead to shorter code. Isn't the whole point of variable names to give a meaningful name so that it helps the user understand what's going on? If the user doesn't know that arr is short for array, that makes the example much harder to understand.
    – Teepeemm
    Jul 25, 2016 at 12:17
  • 1
    @Teepeemm: No, it doesn't. What the reader needs to understand is that you've declared a variable with a certain syntax and that you use it in a certain way. Jul 25, 2016 at 12:37
  • 2
    @Teepeemm: I agree with you. This documentation is for the purpose of teaching programing, and to novice programers it is more helpful if it is clear at all stages in the code that what is being referenced is an array. Our purpose is not to obfuscate the code to deceive the user: we are not writing code intended to defeat software piracy. We actually want our code to be as readily understandable as possible. The term arr1 does not imply that an array is intended, it merely implies that a variable is intended, so IMHO we should use array1 as being much less open to misinterpretation.
    – Ed999
    Jul 25, 2016 at 16:23

2 Answers 2

28

Do not abbreviate names of identifiers. Write proper self documenting code.

Examples should be about the topic they are in. Use comments to explain things related to the topic, not your personal coding style.

If readers have to remember what req or res stands for, they cannot fully concentrate on the actual topic of the example.

but its standard in node.js to use req and res

One goal of this documentation is to overcome shortcomings of existing documentations. Abbreviated identifier names is one such shortcoming.

Its not a shortcoming of existing documentation. Its a standard practice in the entire ecosystem.

Ok I get it, it's a shortcoming of the entire ecosystem then.

I have it seen all too often that people get confused about things like that. Especially if every resource uses the same variable names, people start mindlessly copying this stuff without being knowledgeable about it.

Point in case, an EcmaScript dialect with optional types uses this syntax:

function (parameter:Type):ReturnType

I have seen people using all kinds of things, because they don't know what's going on and they just copy stuff together:

function (Type) // makes no sense, sometimes compiles, but causes all kinds of errors

It's often unclear if parameter can be changed to something else.

I'd rather have documentation write about whats really out there (maybe with a small hint that its standard, but not neccesariliy good)

This is what the syntax section is for, if there's an alternative more commonly used syntax, put it there. As mentioned above, I would not bloat the example with comments on coding style, because you'd have to do this on every example.

A small hint on parameter names here and another small hint on function names there and maybe a little hint on this and a little hint on that and suddenly that simple example on how to handle some requests explodes into a mess of unrelated comments.


tl, dr; I think we all agree that full names would be a better practice. Given that communicating both what's common and what's good should be included in a documentation, I'd put the priority on what's good for examples and mention a different but common approach for naming variables/parameters/etc. outside the code in the syntax section.

8
  • 12
    That might be, but its standard in node.js to use req and res. imho its better to use that in an tutorial, so that the reader is familiar with it when he encounters code thats actually used. One should always strife to understand the ecosystem, too, not only the language. So a short // req is short for request should suffice. Explains the common usage, prepers the reader for the ecosystem, and doesn't need anything else.
    – Polygnome
    Jul 24, 2016 at 13:31
  • 4
    @Polygnome "but its standard in node.js to use req and res" the goal of the documentation is to overcome shortcomings of existing documentations. Abbreviated identifier names is one such shortcoming.
    – null
    Jul 24, 2016 at 13:46
  • 6
    Its not a shortcoming of existing documentation. Its a standard practice in the entire ecosystem.I'd rather have documentation write about whats really out there (maybe with a small hint that its standard, but not neccesariliy good), instead of having a user wonder whats going on later once he reads actual code.
    – Polygnome
    Jul 24, 2016 at 13:49
  • @Polygnome fair enough, answer edited
    – null
    Jul 24, 2016 at 15:00
  • 1
    Very hard to expect documentation to follow standards in abbreviations when it doesn't have any standards at all.
    – e4c5
    Jul 24, 2016 at 23:40
  • 4
    There has to be a tradeoff between descriptive and concise names. You can't just go all verbose all the time and end up with typedef int integer; for (integer loop_counter = 0; loop_counter < array_length; loop_counter++) {...}. Jul 25, 2016 at 6:23
  • @user2357112 there's no loop body in that example so I can only guess the intention of that loop, but given that this loops from 0 to array_length -1 I think that index would be an appropriate name. I agree that there are limits and for example would not rename the type in this case.
    – null
    Jul 25, 2016 at 7:45
  • 2
    @Polygnome: why not go the other way around and say // commonly abbreviated as req
    – Matty
    Jul 25, 2016 at 16:29
7

Sometimes people are new to a language (or framework), and are just about starting to learn it. They, therefore, don't know the standard yet.

Using appropriate names, such as "request" and "response", save them time.

"req" and "res" could as well stand for "requirements" and "result".

Adding a comment to explain the meaning of a variable name is quite always a good sign that the name is poorly chosen.

And sometimes, the standards are bad.

In the other hand, writing "loop_counter" instead of "i" is a waste of time for everyone involved, because loop_counter doesn't provide any additional information to the reader, and requires more time from the writer.

Calling the counter "somethingMeaningfullIndex" could save time to the reader, depending on the complexity of the code.

It's all about common sense and thinking about someone else, or even your future you reading your own code.

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