Naming/abbreviating convention
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
I believe you have to rely in (and enforce) commenting.
PaulowniaK wrote:
document = doc
control = ctrl
parameter = paramFor instance such conventions look a bit difficult to me (that is they don't follow a rule, you have to remember all of them). My 2 cents. :)
Veni, vidi, vici.
-
I believe you have to rely in (and enforce) commenting.
PaulowniaK wrote:
document = doc
control = ctrl
parameter = paramFor instance such conventions look a bit difficult to me (that is they don't follow a rule, you have to remember all of them). My 2 cents. :)
Veni, vidi, vici.
CPallini wrote:
they don't follow a rule
Sort of... "doc" is probably familiar to those Windows users that have MS Office installed. "ctrl" is on your (on mine, at least) keyboard. "param" is, I agree, a bit harder. Hence I thought it'd be nice if there was a set of rules ready to be followed.
Almost, but not quite, entirely unlike... me...
-
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]Keith Barrow wrote:
I'd suggest explicit naming
In deed. That should be the best answer, especially, as you say, memory is no longer a limiting factor, and many of us use wide screen monitors (I had to laugh when my colleagues said his function names got longer since he switched to a wide screen). But, when you have a room full of engineers that can only speak broken English at best, you'd either get a quasi-English sounding function/parameter name that isn't quite right resulting in further confusion, or their native tongue expressed poorly in alphabets... (I've seen both...)
Almost, but not quite, entirely unlike... me...
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
- Insist that they add comments. 2) draw up a set of agreed abbreviations, or impose some if appropriate and insist they are used.
Henry Minute Girl: (staring) "Why do you need an icy cucumber?" “I want to report a fraud. The government is lying to us all.” I wouldn't let CG touch my Abacus! When you're wrestling a gorilla, you don't stop when you're tired, you stop when the gorilla is. Cogito ergo thumb - Sucking my thumb helps me to think.
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
Make the lazy buggers use their kbd, no abbreviations allowed. Same as I will skin the first minion that uses txt speak in their comments. Same goes for method and property names, either type it out or explain why.
Never underestimate the power of human stupidity RAH
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
PaulowniaK wrote:
but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!).
Nothing in documentation is "obvious". Everything needs to be pinned down, unambiguously. Everything is obvious once you understand it; it's quite obvious that my car runs on diesel, not on gasoline. Most common point of failure in IT is miscommunication.
Bastard Programmer from Hell :suss:
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
PaulowniaK wrote:
parameter = param
No,
parameter = parm. :-D There is no standard. -
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]Keith Barrow wrote:
students used to claim this was more typing
Exactly, and more typing (generally) leads to less confusion. They who insist on less typing are just trying to keep the knowledge to themselves and appear "god-like".
-
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]My native tongue is spanish. I teach programming at the university. My strong recomendation is in the first place to use english for ANY kind of expression when programming, that means identifiers: variable names, object names, constants, comments, etc.. anything. Since the reserved words of the languare are in english too, this increments readability of the source code. Also the english words are in averiage shorter than other tongues. The other point to consider is to create an controlled vocabulary for these identifiers that means: if you use customerID to represent , well.. the ID of a general customer you reserve that word for the same purpose when writing other applications.
-
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]Keith Barrow wrote:
That said, there are still systems where memory is at a premium, embedded systems for example
...and people frequently use cross-compilers to target such systems, so variable name length is still not an issue. Duck-naming: If it waddles like a duck and quacks like a duck, call it a duck, not a f*&*ing dck.
-
PaulowniaK wrote:
parameter = param
No,
parameter = parm. :-D There is no standard.Ah, but is parm. reg. parameter registration, or a hard cheese?
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
Abbreviations are the hangover from hand-written/typed documents. There is precisely ZERO reason to employ any sort of abbreviations in this day and age. Including cryptic variable names, such as "bcache" where "IsThisRecordComittedToPermanentStorage" would be superior. With Intellisense, or equivalent, there is NO excuse for any abbreviations.
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
I would say that what is more important than abreviations is it's close cousin acronyms. People invent them all the time and, unlike abbreviations, they are usually very domain specific. It can make it really hard to bring new people onto a project. There is one young buck here who can't write a new line of code without inventing some new acronym. Often they make no sense at all even after he tells you what they mean. If you use them I would urge you to document them somewhere either in code or in a supplemental document.
-
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]In principle I agree with you that naming should be unambiguous and contractions should be avoided. However, I'll take contractions over someone who can't spell. I've worked with a programmer who liked long variable and function names, but couldn't spell. So you'd have to remember his crappy misspelled names and functions to use them. It is awful. Remembering someone's particular contraction spelling does not set my teeth on edge nearly as much. The contractions were never meant to be spelled correctly.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
There isn't a universal "right" abbreviation convention. I'd suggest explicit naming is better as it is less ambiguous. doc for example could mean doctor, document or even dock I suppose. The same goes for method names, they should describe properly what they do. When I was teaching my students used to claim this was more typing, but actually this is a nonsense with (say, Visual Studio's) intellisense. Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable. Abbreviated variable names generally comes from being taught to do it this was by people who really did need to consider the memory implications of longer variable names. For a modern system this is neglible and readability more important. That said, there are still systems where memory is at a premium, embedded systems for example.Sort of a cross between Lawrence of Arabia and Dilbert.[^]
-Or-
A Dead ringer for Kate Winslett[^]Keith Barrow wrote:
Additionally, I'd argue that the time and effort working out what
ctrlmeans more than makes up for any time spend typing the longer names. Additionally it makes the code more readable.Long variable names are more readable in isolation, but when you start stringing them together into expressions it can become much less readable if you aren't careful. No, ctrl vs control isn't going to make much of a difference in that regard, but count vs theNumberOfThingsOnTheStack is.
-Shon
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
Don't think there is any standard for abbreviations, but usually languages have conventions. I can't remember where I saw it in MSDN, but there were guidelines for C#, like: Parameters - Parameter should use camelCase and should not have the type prefixed. i.e: customerID, readOnly, value, customerType Local Variables - Like parameters Member Variables - Prefix with an underscore or "m_". i.e.: _CustomerID, m_CustomerID Class Names - Pascal case and should have at most two uppercase characters in sequence: i.e.: Customer, CustomerType, Guid (instead of GUID), SomeAbbr (Some Abbreviation), SomeAB Method Names - Like Class names Constants - Like Class names Control - Controls should be prefixed with the control type abbreviation (easier to find them with intellisense) and use camel case. i.e.: txtUserName (or tbx), lblPassword Of course in the case of the control, the prefixes should be documented so they can be followed and discoverable by people who may inherit the project. These are just conventions and I believe every company should have its own very well stablished, so at least company-wide, some standard is followed. If not, it at least need to be project wide and documented.
"To alcohol! The cause of, and solution to, all of life's problems" - Homer Simpson "Our heads are round so our thoughts can change direction." ― Francis Picabia
-
Don't think there is any standard for abbreviations, but usually languages have conventions. I can't remember where I saw it in MSDN, but there were guidelines for C#, like: Parameters - Parameter should use camelCase and should not have the type prefixed. i.e: customerID, readOnly, value, customerType Local Variables - Like parameters Member Variables - Prefix with an underscore or "m_". i.e.: _CustomerID, m_CustomerID Class Names - Pascal case and should have at most two uppercase characters in sequence: i.e.: Customer, CustomerType, Guid (instead of GUID), SomeAbbr (Some Abbreviation), SomeAB Method Names - Like Class names Constants - Like Class names Control - Controls should be prefixed with the control type abbreviation (easier to find them with intellisense) and use camel case. i.e.: txtUserName (or tbx), lblPassword Of course in the case of the control, the prefixes should be documented so they can be followed and discoverable by people who may inherit the project. These are just conventions and I believe every company should have its own very well stablished, so at least company-wide, some standard is followed. If not, it at least need to be project wide and documented.
"To alcohol! The cause of, and solution to, all of life's problems" - Homer Simpson "Our heads are round so our thoughts can change direction." ― Francis Picabia
I had to write a document once explaining how to name variables, controls and so on. I was asked to write all the abbreviations and to create something to check if the names where correct. Well, my document was very short. No abbreviations at all. Control names will never be txt, btn, cbo etc. It is textbox, button, combobox, checkbox followed by the name that describes it. I used textbox instead of text because the textSomething is generally a string, while the textboxSomething is the textbox that will receive such string. The only thing that should be used (for that particular project) was to avoid sub-classing names. I don't care if it is a SpeedButton, SomeOtherKindOfButton or a simple Button. The names are always button. Some criticized that not having the right type makes thing hard. In my opinion, needing to know the exact type of the button makes thing hard. If you know there is a button to save, you should look for buttonSave. You don't need to care what kind of button it is (specially if that can change tomorrow).
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
PaulowniaK wrote:
I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions.
Your question isn't as simple as that. It covers all of the following 1. Abbreviations 2. Abbreviations within one language 3. Code documentation. 4. Creation of standards (in regards to the above.) 5. Enforcement of the above. Also implicit with 3-5 is the idea that abbreviations are not always appropriate. Item 5 is probably the most important since, in general, the only effective way to do it is with code reviews. And doing that has more benefits than the other categories.
-
I had to write a document once explaining how to name variables, controls and so on. I was asked to write all the abbreviations and to create something to check if the names where correct. Well, my document was very short. No abbreviations at all. Control names will never be txt, btn, cbo etc. It is textbox, button, combobox, checkbox followed by the name that describes it. I used textbox instead of text because the textSomething is generally a string, while the textboxSomething is the textbox that will receive such string. The only thing that should be used (for that particular project) was to avoid sub-classing names. I don't care if it is a SpeedButton, SomeOtherKindOfButton or a simple Button. The names are always button. Some criticized that not having the right type makes thing hard. In my opinion, needing to know the exact type of the button makes thing hard. If you know there is a button to save, you should look for buttonSave. You don't need to care what kind of button it is (specially if that can change tomorrow).
Paulo Zemek wrote:
Control names will never be txt, btn, cbo etc. It is textbox, button, combobox, checkbox followed by the name that describes it.
I think that if this is documented and team members follow the guidelines it's perfectly fine. I don't really care if it's actually abbreviated or not, I think this is more of a taste thing. Because most people are used to the abbreviation, they shouldn't have problems when the controls are abbreviated, but I agree that having the full name eliminates the risk of confusion. The only disadvantage though, is when you have lines of code that have several control names in it, they usually get clumsy with long names.
Paulo Zemek wrote:
The only thing that should be used (for that particular project) was to avoid sub-classing names.
I don't agree with you here, because, you know, A button is a sub classed control. If you were to follow that all your controls would start with control prefix. But, sub classing in every case may not make sense. If it's a simple subclass, like adding a new property useful for you, then it might not make sense to subclass the name. But, if the behavior is significantly changed (or incremented), then it might make sense to subclass the name.
"To alcohol! The cause of, and solution to, all of life's problems" - Homer Simpson "Our heads are round so our thoughts can change direction." ― Francis Picabia
-
Apologies if this is in the wrong place. I was wondering if people could point me in the right direction with regards to naming and abbreviation conventions. For example, document = doc control = ctrl parameter = param to name a very very few. When you are dealing with people whose native tongue is not English, you tend to get a wide variety of abbreviations, as they don't consider syllables or etymology. The result is pages and pages of enigmatic code full of incomprehensible parameters and functions. It's not so bad if people got in the habit of commenting stuff, but, to whoever wrote the code the abbreviations are clearly obvious (i.e. no need to explain!). (I agree not EVERYTHING needs commenting, but that's only if the parameter/function names are crystal clearly obvious.) I was wondering if there was any resource to which I can point my colleagues to get a hint on how to come up with better parameter names.
Almost, but not quite, entirely unlike... me...
I once programmed in a language that was limited to six-character names in the symbol table. I don't do that anymore. I once programmed in a language where variables were conventionally a single character, maybe with some digits. I don't do that anymore. I once programmed in a language where all variable names that weren't parameters were global to the program. I don't do that anymore. In fact I haven't done any of these things since the mid-80s. Names need to be descriptive and use words - noun phrases. Names can be contextual on method, class, and namespace and not use big noun phrases. If you need a really big name to distinguish items, your current context has become crowded. Refactor something, then continue with short names made unambiguous by context - just like we do in outside life.