4 ms·

I write C for a living but i'm not terribly experienced. I was wondering is there a reason C and C++ code favours comments over descriptive names? I'm almost c

by AJRF 8y ago

I write C for a living but i'm not terribly experienced. I was wondering is there a reason C and C++ code favours comments over descriptive names? I'm almost certain i'm not making this up, but go into any random file here and look at the names. Structs will have members called p with a comment saying "position". It seems very silly.

MaulingMonkey 8y ago
Some old C code was written on monochrome 80x25 ttys. Or written by mathematicians who will be confused why you haven't simplified "position" down to "-p(o2)stn", because clearly "position" is multiplying 8 variables together. Or typed on a broken keyboard, hence "creat" I assume. Or written on programmers who remember, or were still using, punchcards. And maybe have some RSI and no IDE autocompletion to help. And of coure any new C code would look out of place if it didn't follow these old shibboleths... better make new C code an unreadable mess too, no? ;)
- eru 8y ago
  Not all of math is done in commutative rings.
enriquto 8y ago
> Structs will have members called p with a comment saying "position". It seems very silly. It does not seem silly to me. Coming from mathematics, single-letter variable names are the only acceptable possibility, especially in numerical code. I tend to read contiguous letters in a formula as products. Besides, descriptive variable names violate the principle of "don't repeat yourself". It is better to describe the variable only once, in a comment next to its declaration, instead of several times. Programmers should understand that not everybody who programs has a background in computer science, and certainly the traditional conventions of computer science are not universal and not generally reasonable. Many of us have a scientific background, where descriptive variable names are silly. We do not want our numbers to have meaning, that's the whole point of abstraction. Thus, they are named x, y, z, and so on.
- v_lisivka 8y ago
  If you are doing engineering, then it better to follow engineering best practices, with descriptive names. If you are doing science, it's better to follow science best practices. For example, we have two competing coordinate systems: first is x // width, y // height, z // depth, and second is x // width, y // depth, z // height. With descriptive names we will have no such problem. However, it's much easier to load large and complex algorithm into head if it written concisely: one letter per variable or function, minimum unnecessary separators. When I need to understand someone else codebase, I will often concatenate all files, delete all comments and obvious functions (getters, setters, eq, hash, etc.), abbreviate long names via search and replace, remove unnecessary symbols and convert functions and classes into oneliners, until I will see whole algorithm at once. However, reading of such code requires some additional training. To summarize, it's possible and is easy to convert descriptive names into abbreviations, so, it's better to stick with descriptive naming in public interfaces.
- deleted 8y ago
  [deleted]
- mjburgess 8y ago
  Programming languages are not mathematics, better to put your mathematics in the comments, than the reverse. force = (g_constant * mass[0] * mass[1])/(radius 2) Communicates far more than the algebraic alternative. Programming is about solving a particular problem, not providing a general formalism. The art of it, and mastery of it, is how to imbue the program with the problem domain. So that by speaking in its concepts you solve the problem. > violate the principle of "don't repeat yourself" That isnt the principle, that's a literal reading of each word conjoined into something totally different. The principle is "solve the problem once", ie., if you encounter code re-solving a problem already solved before, abstract such that you solve it only once. The principle only makes sense with respect to a problem which reoccurs, it is either incoherent or false when applied to literal fragments of code text. One would then be moved to define replacement macros for anything more than two letters.
  - enriquto 8y ago
abcd_f 8y ago
Where did you see that exactly? Looked at several headers at random just now (including file, net) and they seem OK. Not terribly verbose, but not exactly cryptic. In terms of 'p' vs 'position' - 'p' is an extreme and it's usually used for pointers, but the driving factor for using shorter names is usually to keep the line length in check when these vars are used in the code. Ditto for type names. "Position" is quite often shorten to "pos", "offset" to "off", "length" to "len", etc. This is very common. Sometimes the original name is too long (e.g. "position of the last error in the first block") and lands itself to a not-so-obvious abbreviation, in which case the comment is made to clarify what it is. It's basically about striking a balance between succinctness and verbosity, and conventionally C tends to lean towards the former.
- blattimwind 8y ago
  The C++ standard library continued this culture of "making names unreasonably short and/or adding modifiers that are anything but obvious", e.g. rdbuf, setf, seekg/p, tellg/p, beg (instead of begin[ing]), ends etc.
  - garaetjjte 8y ago
    I prefer that instead of boost-like std::chrono::time_point<std::chrono::high_resolution_clock>
    - blattimwind 8y ago
      std::datetime::timepoint<std::datetime::highres> ? Assuming you'd want to keep a separate datetime namespace. Neither ::highres nor ::high_resolution_clock really is a descriptive name though, because it doesn't really describe what it means. What is a "high resolution clock" here? Does it mean µs resolution? Nanoseconds (as some "newer" Linux APIs support)? What about accuracy? "chrono" is one of these "sounds cool but is kind of a weird word to use" things.
flohofwoe 8y ago
It's mostly a matter of personal taste IMHO, has nothing to do with being C or C++, much like brace- or tab-style. My own rule of thumb is: short names for 'unimportant' variables where the meaning is clear from the context. More descriptive names for the more non-obvious cases, but still keep it short and concise (e.g. I would typically use "pos" instead of "position"). Having said that, some early C dialects limited the significant number of characters in identifiers to 6 or 8. I heard that this is the reason why the C runtime library function names are short (like strcpy() instead of string_copy()).
Someone 8y ago
The original compiler ran on a platform was heavily resource constrained (very little memory, slow terminals). If all you have is a 300 baud terminal (a luxury for some early users), writing a 30-letter statement takes about a second. Doubling that speed by using shorter identifiers is worth it (certainly as long as all the people reading the code either wrote it, or have the writer sitting next to them) That created a culture that persists to today. There are different cultural streams such as Apple’s one, which originated in Pascal (for the original Mac OS). Consequently (I think), Apple’s C headers later on weren’t afraid to use identifiers with over 40 characters. Next step/Cocoa similarly aren’t afraid of long names (https://mackuba.eu/2010/10/31/the-longest-names-in-cocoa/ https://mackuba.eu/2010/10/31/the-longest-names-in-cocoa/)
skocznymroczny 8y ago
I think a lot of C/C++ programmers use text editors such as Vim/Emacs, and might not have code completion support, so the shorter names are easier to type.
- drainyard 8y ago
  Most people that use either Emacs or Vim for serious programming use extensions that implement code completion.
- westmeal 8y ago
  'dabbrev-expand works in the context of the files that are open in all of the buffers in the buffer list too

by AJRF 8y ago

MaulingMonkey 8y ago

Some old C code was written on monochrome 80x25 ttys. Or written by mathematicians who will be confused why you haven't simplified "position" down to "-p(o2)stn", because clearly "position" is multiplying 8 variables together. Or typed on a broken keyboard, hence "creat" I assume. Or written on programmers who remember, or were still using, punchcards. And maybe have some RSI and no IDE autocompletion to help. And of coure any new C code would look out of place if it didn't follow these old shibboleths... better make new C code an unreadable mess too, no? ;)

eru 8y ago
Not all of math is done in commutative rings.

enriquto 8y ago

> Structs will have members called p with a comment saying "position". It seems very silly. It does not seem silly to me. Coming from mathematics, single-letter variable names are the only acceptable possibility, especially in numerical code. I tend to read contiguous letters in a formula as products. Besides, descriptive variable names violate the principle of "don't repeat yourself". It is better to describe the variable only once, in a comment next to its declaration, instead of several times. Programmers should understand that not everybody who programs has a background in computer science, and certainly the traditional conventions of computer science are not universal and not generally reasonable. Many of us have a scientific background, where descriptive variable names are silly. We do not want our numbers to have meaning, that's the whole point of abstraction. Thus, they are named x, y, z, and so on.

v_lisivka 8y ago
If you are doing engineering, then it better to follow engineering best practices, with descriptive names. If you are doing science, it's better to follow science best practices. For example, we have two competing coordinate systems: first is x // width, y // height, z // depth, and second is x // width, y // depth, z // height. With descriptive names we will have no such problem. However, it's much easier to load large and complex algorithm into head if it written concisely: one letter per variable or function, minimum unnecessary separators. When I need to understand someone else codebase, I will often concatenate all files, delete all comments and obvious functions (getters, setters, eq, hash, etc.), abbreviate long names via search and replace, remove unnecessary symbols and convert functions and classes into oneliners, until I will see whole algorithm at once. However, reading of such code requires some additional training. To summarize, it's possible and is easy to convert descriptive names into abbreviations, so, it's better to stick with descriptive naming in public interfaces.
deleted 8y ago
[deleted]
mjburgess 8y ago
Programming languages are not mathematics, better to put your mathematics in the comments, than the reverse. force = (g_constant * mass[0] * mass[1])/(radius 2) Communicates far more than the algebraic alternative. Programming is about solving a particular problem, not providing a general formalism. The art of it, and mastery of it, is how to imbue the program with the problem domain. So that by speaking in its concepts you solve the problem. > violate the principle of "don't repeat yourself" That isnt the principle, that's a literal reading of each word conjoined into something totally different. The principle is "solve the problem once", ie., if you encounter code re-solving a problem already solved before, abstract such that you solve it only once. The principle only makes sense with respect to a problem which reoccurs, it is either incoherent or false when applied to literal fragments of code text. One would then be moved to define replacement macros for anything more than two letters.
- enriquto 8y ago

abcd_f 8y ago

Where did you see that exactly? Looked at several headers at random just now (including file, net) and they seem OK. Not terribly verbose, but not exactly cryptic. In terms of 'p' vs 'position' - 'p' is an extreme and it's usually used for pointers, but the driving factor for using shorter names is usually to keep the line length in check when these vars are used in the code. Ditto for type names. "Position" is quite often shorten to "pos", "offset" to "off", "length" to "len", etc. This is very common. Sometimes the original name is too long (e.g. "position of the last error in the first block") and lands itself to a not-so-obvious abbreviation, in which case the comment is made to clarify what it is. It's basically about striking a balance between succinctness and verbosity, and conventionally C tends to lean towards the former.

blattimwind 8y ago
The C++ standard library continued this culture of "making names unreasonably short and/or adding modifiers that are anything but obvious", e.g. rdbuf, setf, seekg/p, tellg/p, beg (instead of begin[ing]), ends etc.
- garaetjjte 8y ago
  I prefer that instead of boost-like std::chrono::time_point<std::chrono::high_resolution_clock>
  - blattimwind 8y ago
    std::datetime::timepoint<std::datetime::highres> ? Assuming you'd want to keep a separate datetime namespace. Neither ::highres nor ::high_resolution_clock really is a descriptive name though, because it doesn't really describe what it means. What is a "high resolution clock" here? Does it mean µs resolution? Nanoseconds (as some "newer" Linux APIs support)? What about accuracy? "chrono" is one of these "sounds cool but is kind of a weird word to use" things.

flohofwoe 8y ago

It's mostly a matter of personal taste IMHO, has nothing to do with being C or C++, much like brace- or tab-style. My own rule of thumb is: short names for 'unimportant' variables where the meaning is clear from the context. More descriptive names for the more non-obvious cases, but still keep it short and concise (e.g. I would typically use "pos" instead of "position"). Having said that, some early C dialects limited the significant number of characters in identifiers to 6 or 8. I heard that this is the reason why the C runtime library function names are short (like strcpy() instead of string_copy()).

Someone 8y ago

The original compiler ran on a platform was heavily resource constrained (very little memory, slow terminals). If all you have is a 300 baud terminal (a luxury for some early users), writing a 30-letter statement takes about a second. Doubling that speed by using shorter identifiers is worth it (certainly as long as all the people reading the code either wrote it, or have the writer sitting next to them) That created a culture that persists to today. There are different cultural streams such as Apple’s one, which originated in Pascal (for the original Mac OS). Consequently (I think), Apple’s C headers later on weren’t afraid to use identifiers with over 40 characters. Next step/Cocoa similarly aren’t afraid of long names (https://mackuba.eu/2010/10/31/the-longest-names-in-cocoa/ https://mackuba.eu/2010/10/31/the-longest-names-in-cocoa/)

skocznymroczny 8y ago

I think a lot of C/C++ programmers use text editors such as Vim/Emacs, and might not have code completion support, so the shorter names are easier to type.

drainyard 8y ago
Most people that use either Emacs or Vim for serious programming use extensions that implement code completion.
westmeal 8y ago
'dabbrev-expand works in the context of the files that are open in all of the buffers in the buffer list too