This question already has an answer here:
What is Hungarian Notation? [duplicate]
(1 answer)
Closed 8 months ago.
I have recently started working in a system that includes the data type in the fieldnames for every record. I'm writing up the documentation for this system (in particular the coding conventions), and as a history lesson, I wanted to include a reference to this style of naming convention.
In the past, I know it was very standard to use names like
dim strName
dim intAge
dim fltIncome
To help keep track of datatypes in dynamically typed languages (VBS in the case above). I also, know that this convention was actually named after somebody who wrote a lengthy description about why this is a good idea.
Does anyone know the name of this convention, or have good references they could share?
COM doesn't use Hungarian Notation at all. The Windows API does. And its useful enough. I've bolded the pat below that refutes Hungarian Notation in COM.
This is from https://learn.microsoft.com/ms-my/previous-versions/windows/desktop/automat/naming-conventions
Choose names for exposed objects, properties, and methods that can be
easily understood by users of the application. The guidelines in this
section apply to all of the following exposed items:
Objects — implemented as classes in an application.
Properties and methods — implemented as members of a class.
Named arguments — implemented as named parameters in a member function.
Constants and enumerations — implemented as settings for properties and methods.
Use Entire Words or Syllables
It is easier for users to remember complete words than to remember
whether you abbreviated Window as Wind, Wn, or Wnd.
When you need to abbreviate because an identifier would be too long,
try to use complete initial syllables. For example, use AltExpEval
instead of AlternateExpressionEvaluation.
Use Don't use
Application App
Window Wnd
Use Mixed Case
All identifiers should use mixed case, rather than underscores, to
separate words.
Use Don't use
ShortcutMenus Shortcut_Menus, Shortcutmenus, SHORTCUTMENUS, SHORTCUT_MENUS
BasedOn basedOn
Use the Same Word Used in the Interface
Use consistent terminology. Do not use names like HWND that are
based on Hungarian notation. Try to use the same word users would
use to describe a concept.
Use Don't use
Name Lbl
Use the Correct Plural for the Class Name
Collection classes should use the correct plural for the class name.
For example, if you have a class named Axis, store the collection of
Axis objects in an Axes class. Similarly, a collection of Vertex
objects should be stored in a Vertices class. In cases where English
uses the same word for the plural, append the word "Collection."
Use Don't use
Axes Axiss
SeriesCollection CollectionSeries
Windows ColWindow
Related
.tmlanguage files work by defining a list of key value pairs. Regular expressions are the keys and the type of syntax is the value. This is done in the following XML-ish manner:
<key>match</key>
<string>[0-9]</string>
<key>name</key>
<string>constant.numeric</string>
My main question is: Is there a list of values that could go in place of constant.numeric if the file is to be used by a text editor like Sublime?
For a basic introduction, check out the Language Grammars section of the TextMate Manual. The Naming Conventions section describes some of the base scopes, like comment, keyword, meta, storage, etc. These classes can then be subclassed to give as much detail as possible - for example, constant.numeric.integer.long.hexadecimal.python. However, it is very important to note that these are not hard-and-fast rules - just suggestions. This will become obvious as you scan through different language definitions and see, for example, all the different ways that functions are scoped - meta.function-call, support.function.name, meta.function-call punctuation.definition.parameters, etc.
The best way to learn about scopes is to examine existing .tmLanguage files, and to look through the source of different languages and see what scopes are assigned where. The XML format is very difficult to casually browse through, so I use the excellent PackageDev plugin to translate the XML to YAML. It is then much easier to scan and see what scopes are described by what regexes:
Another way to learn is to see how different language constructs are scoped, and for that I highly recommend using ScopeAlways. Once installed and activated, just place your cursor and the scope(s) that apply to that particular position are shown in the status bar. This is particularly useful when designing color schemes, as you can easily see which selectors will highlight a language feature of interest.
If you're interested, the color scheme used here is Neon, which I designed to make as many languages as possible look as good as possible, covering as many scopes as possible. Feel free to look through it to see how the different language elements are highlighted; this could also help you in designing your .tmLanguage to be consistent with other languages.
I hope all this helps, good luck!
Yes. The .tmlanguage format was originally used by TextMate. The TextMate manual provides full documentation for the format, including the possible types of language constructs.
Copied from the relevant docs page, in hierarchical format:
comment — for comments.
line — line comments, we specialize further so that the type of comment start character(s) can be extracted from the scope
double-slash — // comment
double-dash — -- comment
number-sign — # comment
percentage — % comment
character — other types of line comments.
block — multi-line comments like /* … */ and <!-- … -->.
documentation — embedded documentation.
constant — various forms of constants.
numeric — those which represent numbers, e.g. 42, 1.3f, 0x4AB1U.
character — those which represent characters, e.g. <, \e, \031.
escape — escape sequences like \e would be constant.character.escape.
language — constants (generally) provided by the language which are “special” like true, false, nil, YES, NO, etc.
other — other constants, e.g. colors in CSS.
entity — an entity refers to a larger part of the document, for example a chapter, class, function, or tag. We do not scope the entire entity as entity.* (we use meta.* for that). But we do use entity.* for the “placeholders” in the larger entity, e.g. if the entity is a chapter, we would use entity.name.section for the chapter title.
name — we are naming the larger entity.
function — the name of a function.
type — the name of a type declaration or class.
tag — a tag name.
section — the name is the name of a section/heading.
other — other entities.
inherited-class — the superclass/baseclass name.
attribute-name — the name of an attribute (mainly in tags).
we are naming the larger entity.
invalid — stuff which is “invalid”.
illegal — illegal, e.g. an ampersand or lower-than character in HTML (which is not part of an entity/tag).
deprecated — for deprecated stuff e.g. using an API function which is deprecated or using styling with strict HTML.
keyword — keywords (when these do not fall into the other groups).
control — mainly related to flow control like continue, while, return, etc.
operator — operators can either be textual (e.g. or) or be characters.
other — other keywords.
markup — this is for markup languages and generally applies to larger subsets of the text.
underline — underlined text.
link — this is for links, as a convenience this is derived from markup.underline so that if there is no theme rule which specifically targets markup.underline.link then it will inherit the underline style.
bold — bold text (text which is strong and similar should preferably be derived from this name).
heading — a section header. Optionally provide the heading level as the next element, for example markup.heading.2.html for <h2>…</h2> in HTML.
italic — italic text (text which is emphasized and similar should preferably be derived from this name).
list — list items.
numbered — numbered list items.
unnumbered — unnumbered list items.
quote — quoted (sometimes block quoted) text.
raw — text which is verbatim, e.g. code listings. Normally spell checking is disabled for markup.raw.
other — other markup constructs.
meta — the meta scope is generally used to markup larger parts of the document. For example the entire line which declares a function would be meta.function and the subsets would be storage.type, entity.name.function, variable.parameter etc. and only the latter would be styled. Sometimes the meta part of the scope will be used only to limit the more general element that is styled, most of the time meta scopes are however used in scope selectors for activation of bundle items. For example in Objective-C there is a meta scope for the interface declaration of a class and the implementation, allowing the same tab-triggers to expand differently, depending on context.
storage — things relating to “storage”.
type — the type of something, class, function, int, var, etc.
modifier — a storage modifier like static, final, abstract, etc.
string — strings.
quoted — quoted strings.
single — single quoted strings: 'foo'.
double — double quoted strings: "foo".
triple — triple quoted strings: """Python""".
other — other types of quoting: $'shell', %s{...}.
unquoted — for things like here-docs and here-strings.
interpolated — strings which are “evaluated”: `date`, $(pwd).
regexp — regular expressions: /(\w+)/.
other — other types of strings (should rarely be used).
support — things provided by a framework or library should be below support.
function — functions provided by the framework/library. For example NSLog in Objective-C is support.function.
class — when the framework/library provides classes.
type — types provided by the framework/library, this is probably only used for languages derived from C, which has typedef (and struct). Most other languages would introduce new types as classes.
constant — constants (magic values) provided by the framework/library.
variable — variables provided by the framework/library. For example NSApp in AppKit.
other — the above should be exhaustive, but for everything else use support.other.
variable — variables. Not all languages allow easy identification (and thus markup) of these.
parameter — when the variable is declared as the parameter.
language — reserved language variables like this, super, self, etc.
other — other variables, like $some_variables.
When writing comments, I sometimes find myself needing to talk about a type (class, struct, etc.) in plural when writing comments, such as:
/*
* getThings
* Get a list of --> Things <-- from somewhere.
*/
Thing *getThings(void);
The problem is, the type name is singular (namely, Thing), but I want to talk about them in plural in comments.
If I say Things, it suggests to the reader it's talking about a type called Things, which is not the case. If I say Thing's, it looks awkward because it's not grammatically correct (it's either possessive or "Thing is", not plural). I could talk around the problem and say a list of Thing items
What's a good convention to stick to when writing plurals of types?
Well, depending on the documentation system you're using, you can wrap the name of the type in a special syntax and put the s outside it. For example:
.NET XML comments
Get a list of <see cref="Thing"/>s from somewhere.
doxygen C/C++ comments
Get a list of \link Thing \endlink s from somewhere.
Not 100% certain on the doxygen variant but it should be something like that.
And if you're not using a particular documentation system and thus have no special comments, I'd do something like:
Get a list of [Thing]s from somewhere.
Or you could use ( ) or { }, depending on preference...
I would use the 's' in parentheses.
/* Get a list of Thing(s) from somewhere */
MSDN Guidelines states that class names should be Pascal cast with no special prefix, such as "C".
It is also states that names of class members, such as proprties and fields, should also be Pascal cast.
So, names ambiguity may arise in the case of a naming generic object.
for example, consider a class named "Polynom". An object instantiate from this class shuold be named "Polynom" also. Polynom = new Polynom.
Is it?
I think a more common guideline (that I have seen Microsoft themselves follow) is to name variables, including instances, camel-cased (lower first, upper all other words: variableName). So in your case, it would be polynom = new Polynom. Of course, I wouldn't actually name a variable polynom unless it had a very obvious use and only for a local space. Otherwise a variable name should describe what it does, not what type it is.
All that said, the most important part of any naming convention is not what casing goes where but that you are consistent with it. Find something that works for you and stick to it!
[Quick edit: re-reading your question again, I see that you're mainly concerned about Properties. In this case, yes, it is very common to Pascal case them, so Polynom would be resonable. But since this is a property that would be exposed to the user (otherwise why is it a property?) Please don't name it Polynom!!! Do something more descriptive, we have intellisense if we want to know the type.]
You may often see
PolyNom polyNom = new PolyNom();
Although most of the time this is not the most readable code. Is it just any old polyNom, or is it for a specific purpose. Steve McConnell sites in Code Complete that the optimal variable name length for debugging (reading code) is 10-16 characters, with 8-20 characters being about the same (pg. 262 second ed.) this gives you a lot of room to more accurately describe exactly what your variable is.
Edit: There appears to be at least two valid reasons why Smalltalkers do this (readability during message chaining and scoping issues) but perhaps the question can remain open longer to address general usage.
Original: For reasons I've long forgotten, I never use articles in my variable names. For instance:
aPerson, theCar, anObject
I guess I feel like articles dirty up the names with meaningless information. When I'd see a coworker's code using this convention, my blood pressure would tick up oh-so-slightly.
Recently I've started learning Smalltalk, mostly because I want to learn the language that Martin Fowler, Kent Beck, and so many other greats grew up on and loved.
I noticed, however, that Smalltalkers appear to widely use indefinite articles (a, an) in their variable names. A good example would be in the following Setter method:
name: aName address: anAddress.
self name: aName.
self address: anAddress
This has caused me to reconsider my position. If a community as greatly respected and influential as Smalltalkers has widely adopted articles in variable naming, maybe there's a good reason for it.
Do you use it? Why or why not?
This naming convention is one of the patterns in Kent Beck's book Smalltalk Best Practice Patterns. IMHO this book is a must-have even for non-smalltalkers, as it really helps naming things and writing self-documenting code. Plus it's probably one of the few pattern langages to exhibit Alexander's quality without a name.
Another good book on code patterns is Smalltalk with Style, which is available as a free PDF.
Generally, the convention is that instance variables and accessors use the bare noun, and parameters use the indefinite article plus either a role or a type, or a combination. Temporary variables can use bare nouns because they rarely duplicate the instance variable; alternatively, it's quite frequent to name them with more precision than just an indefinite article, in order to indicate their role in the control flow: eachFoo, nextFoo, randomChild...
It is in common use in Smalltalk as a typeless language because it hints the type of an argument in method call. The article itself signals that you are dealing with an instance of some object of specified class.
But remember that in Smalltalk the methods look differently, we use so called keyword messages and it this case the articles actually help the readability:
anAddressBook add: aPerson fromTownNamed: aString
I think I just found an answer. As Konrad Rudolph said, they use this convention because of a technical reason:
...this means it [method variable] cannot duplicate the name of an instance variable, a temporary variable defined in the interface, or another temporary variable.
-IBM Smalltalk Tutorial
Basically a local method variable cannot be named the same as an object/class variable. Coming from Java, I assumed a method's variables would be locally scoped, and you'd access the instance variables using something like:
self address
I still need to learn more about the method/local scoping in Smalltalk, but it appears they have no other choice; they must use a different variable name than the instance one, so anAddress is probably the simplest approach. Using just address results in:
Name is already defined ->address
if you have an instance variable address defined already...
I always felt the articles dirtied up the names with meaningless information.
Exactly. And this is all the reason necessary to drop articles: they clutter the code needlessly and provide no extra information.
I don’t know Smalltalk and can't talk about the reasons for “their” conventions but everywhere else, the above holds. There might be a simple technical reason behind the Smalltalk convention (such as ALL_CAPS in Ruby, which is a constant not only by convention but because of the language semantics).
I wobble back and forth on using this. I think that it depends on the ratio of C++ to Objective C in my projects at any given time. As for the basis and reasoning, Smalltalk popularized the notion of objects being "things". I think that it was Yourdon and Coad that strongly pushed describing classes in the first person. In Python it would be something like the following snippet. I really wish that I could remember enough SmallTalk to put together a "proper" example.
class Rectangle:
"""I am a rectangle. In other words, I am a polygon
of four sides and 90 degree vertices."""
def __init__(self, aPoint, anotherPoint):
"""Call me to create a new rectangle with the opposite
vertices defined by aPoint and anotherPoint."""
self.myFirstCorner = aPoint
self.myOtherCorner = anotherPoint
Overall, it is a conversational approach to program readability. Using articles in variable names was just one portion of the entire idiom. There was also an idiom surrounding the naming of parameters and message selectors IIRC. Something like:
aRect <- [Rectangle createFromPoint: startPoint
toPoint: otherPoint]
It was just another passing fad that still pops up every so often. Lately I have been noticing that member names like myHostName are popping up in C++ code as an alternative to m_hostName. I'm becoming more enamored with this usage which I think hearkens back to SmallTalk's idioms a little.
Never used, maybe because in my main language there are not any articles :P
Anyway i think that as long as variable's name is meaningful it's not important if there are articles or not, it's up to the coder's own preference.
Nope. I feel it is waste of characters space and erodes the readability of your code. I might use variations of the noun, for example Person vs People depending on the context. For example
ArrayList People = new ArrayList();
Person newPerson = new Person();
People.add(newPerson);
No I do not. I don't feel like it adds anything to the readability or maintainability of my code base and it does not distinguish the variable for me in any way.
The other downside is if you encourage articles in variable names, it's just a matter of time before someone does this in your code base.
var person = new Person();
var aPerson = GetSomeOtherPerson();
Where I work, the standard is to prefix all instance fields with "the-", local variables with "my-" and method parameters with "a-". I believe this came about because many developers were using text editors like vi instead of IDE's that can display different colors per scope.
In Java, I'd have to say I prefer it over writing setters where you dereference this.
Compare
public void setName(String name) {
this.name = name;
}
versus
public void setName(String aName) {
theName = aName;
}
The most important thing is to have a standard and for everyone to adhere to it.
For some reason I never see this done. Is there a reason why not? For instance I like _blah for private variables, and at least in Windows Forms controls are by default private member variables, but I can't remember ever seeing them named that way. In the case that I am creating/storing control objects in local variables within a member function, it is especially useful to have some visual distinction.
This might be counter-intuitive for some, but we use the dreaded Hungarian notation for UI elements.
The logic is simple: for any given data object you may have two or more controls associated with it. For example, you have a control that indicates a birth date on a text box, you will have:
the text box
a label indicating that the text box is for birth dates
a calendar control that will allow you to select a date
For that, I would have lblBirthDate for the label, txtBirthDate for the text box, and calBirthDate for the calendar control.
I am interested in hearing how others do this, however. :)
Hungarian notation or not, I'm more curious if people prepend m_ or _ or whatever they use for standard private member variables.
I personally prefix private objects with _
Form controls are always prefixed with the type, the only reason I do this is because of intellisense. With large forms it becomes easier to "get a labels value" by just typing lbl and selecting it from the list ^_^ It also follows the logic stated by Jon Limjap.
Although this does go again Microsofts .NET Coding Guidelines, check them out here.
For me, the big win with the naming convention of prepending an underscore to private members has to do with Intellisense. Since underscore precedes any letter in the alphabet, when I do a ctrl-space to bring up Intellisense, there are all of my _privateMembers, right at the top.
Controls, though, are a different story, as far as naming goes. I think that scope is assumed, and prepending a few letters to indicate type (txtMyGroovyTextbox, for example) makes more sense for the same reason; controls are grouped in Intellisense by type.
But at work, it's VB all the way, and we do mPrivateMember. I think the m might stand for module.
I came through VB and have held onto the control type prefix for controls. My private members use lower-camel case (firstLetterLowercase) while public members use Pascal/upper-camel case (FirstLetterUppercase).
If there are too many identifiers/members/locals to have a 90% chance of remembering/guessing what it is called, more abstraction is probably necessary.
I have never been convinced that a storage type prefix is useful and/or necessary. I do, however, make a strong habit of following the style of whatever code I am using.
I don't, but I appreciate your logic. I guess the reason most people don't is that underscores would look kind of ugly in the Properties window at design time. It'd also take up an extra character of horizontal space, which is at a premium in a docked window like that.
Hungarian notation or not, I'm more
curious if people prepend m_ or _ or
whatever they use for standard private
member variables.
Luke,
I use _ prefix for my class library objects. I use Hungarian notation exclusively for the UI, for the reason I stated.
I never use underscores in my variable names. I've found that anything besides alpha (sometimes alphanumeric) characters is excessive unless demanded by the language.
I'm in the Uppercase/Lowercase camp ("title" is private, "Title" is public), mixed with the "hungarian" notation for UI Components (tbTextbox, lblLabel etc.), and I am happy that we do not have Visual Case-Insensitive-Basic developers in the team :-)
I don't like the underscore because it looks kinda ugly, but I have to admit it has an advantage (or a disadvantage, depending on your point): In the debugger, all the private Variables will be on top due to the _ being on top of the alphabet. But then again, I prefer my private/public pair to be together, because that allows for easier debugging of getter/setter logic as you see the private and public property next to each other,
I write down the name of the database column they represent.
I use m_ for member variables, but I'm increasingly becoming tempted to just using lowerCamelCase like I do for method parameters and local variables. Public stuff is in UpperCamelCase.
This seems to be more or less accepted convention across the .NET community.