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.
arr1
is short for "array 1". All they need to know is thatarr1
is a variable with that name, which is distinct fromarr2
.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 thatarr
is short for array, that makes the example much harder to understand.arr1
does not imply that an array is intended, it merely implies that a variable is intended, so IMHO we should usearray1
as being much less open to misinterpretation.