It's a random and stupid question, but I have no clue what the i stands for in structs with members like:
[starting character]i_[some specifier]
Examples are like: bio struct, everytime dm_target is referenced, bvec_iter.
Whenever I read such a variable I read the complete name in my head, and it's very frustrating to me that I can't do it with these.
There no meaning in i_, it's not special.
A loooong time ago structure members shared the same namespace as variables and such, they had to be unique - some people are used to that. And it is subjectively nice to have structure members starting with a unique prefix - IDE autocompletion works better, and it's easier to do lookup.
In the case of struct bio members, bi_ is just a shortcut for... bio_.
In the case of struct dm_target *ti variable name, ti looks like a nice shorter form of this used in C++ and Python for referencing the current object.
In the case of struct bvec_iter, bi_ is just a shorthand of bvec_iter. Above, you have struct bio_vec that uses bv_ for struct members.
These are just conventions that a specific developer used to mark some abstractions in their source code. It has no specific meaning.
It's also easier to look sometimes - when I see iter->bi_stuff, I can "suspect" that iter is a pointer to something bi related (bio? bvec_iter?). In the context of many, many variables, such small clues are nice for the eye.
This all is subjective. It is way more important to follow one convention, rather that what convention it is.
Related
The Effective go has following advice on naming of getters:
Go doesn't provide automatic support for getters and setters. There's
nothing wrong with providing getters and setters yourself, and it's
often appropriate to do so, but it's neither idiomatic nor necessary
to put Get into the getter's name. If you have a field called owner
(lower case, unexported), the getter method should be called Owner
(upper case, exported), not GetOwner. The use of upper-case names for
export provides the hook to discriminate the field from the method. A
setter function, if needed, will likely be called SetOwner. Both names
read well in practice:
Source: https://golang.org/doc/effective_go.html#Getters
Now, this advice doesn't seem to consistent as the stdlib itself violates this multiple times.
As you can see in above screenshot, there are multiple methods which use GetX naming convention which is advised against in the effective go guide.
So the question is is the advice given in guide wrong or these methods are named wrongly & would be fixed in future versions?
These names are not consistent with Go naming by design. Rob Pike, one of the Go creators, says this about the names in the OS package:
There are inconsistencies but this is the key point. It should be Stdout not StdOut, because that name is coming from the underlying system. Similarly it's Fprintf not FPrintf or FPrintF because that is a very familiar name. These names are coming into Go, not being created there, and the initial cap is the admission fee.
The names will not be changed in a future version of Go.
[go-nuts] FunctionName caseinconsistencies
A lot of the all lowercase names were chosen before we had really
figured out what the naming conventions should be. The rule we
adopted, which might be worth revisiting later, was that entry points
in package os or syscall, which are named after equivalents in C, just
had a single capital at the beginning, to avoid needing to decide
where the internal capitalizations are in abbreviations like geteuid
or getwd or chdir. Names like Readdirnames, which are actual words,
might be worth revisiting at some point.
Russ
os: inconsistent casing in names #1187
Is there any sort of rule about the casing of functions used in the
"os" package? Looking through, it doesn't sound like it's very easy
to recall whether a given function should be called LikeThat or
Likethat.
For instance:
Mkdir
MkdirAll
TempDir
Getenv
ForkExec
Readlink
ReadAt
Readdir
It feels very ad-hoc, and hard to recall.
It's a known issue. It's unplanned.
The term "getters" refers to methods on structs that allow you to read values of (often unexported) fields on that struct. The functions you're pointing to are top-level functions which allow you to read values from the OS. That idiomatic rule is not relevant to this case.
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 */
It seems like people who would never dare cut and paste code have no problem specifying the type of something over and over and over. Why isn't it emphasized as a good practice that type information should be declared once and only once so as to cause as little ripple effect as possible throughout the source code if the type of something is modified? For example, using pseudocode that borrows from C# and D:
MyClass<MyGenericArg> foo = new MyClass<MyGenericArg>(ctorArg);
void fun(MyClass<MyGenericArg> arg) {
gun(arg);
}
void gun(MyClass<MyGenericArg> arg) {
// do stuff.
}
Vs.
var foo = new MyClass<MyGenericArg>(ctorArg);
void fun(T)(T arg) {
gun(arg);
}
void gun(T)(T arg) {
// do stuff.
}
It seems like the second one is a lot less brittle if you change the name of MyClass, or change the type of MyGenericArg, or otherwise decide to change the type of foo.
I don't think you're going to find a lot of disagreement with your argument that the latter example is "better" for the programmer. A lot of language design features are there because they're better for the compiler implementer!
See Scala for one reification of your idea.
Other languages (such as the ML family) take type inference much further, and create a whole style of programming where the type is enormously important, much more so than in the C-like languages. (See The Little MLer for a gentle introduction.)
It isn't considered a bad thing at all. In fact, C# maintainers are already moving a bit towards reducing the tiring boilerplate with the var keyword, where
MyContainer<MyType> cont = new MyContainer<MyType>();
is exactly equivalent to
var cont = new MyContainer<MyType>();
Although you will see many people who will argue against var usage, which kind of shows that many people is not familiar with strong typed languages with type inference; type inference is mistaken for dynamic/soft typing.
Repetition may lead to more readable code, and sometimes may be required in the general case. I've always seen the focus of DRY being more about duplicating logic than repeating literal text. Technically, you can eliminate 'var' and 'void' from your bottom code as well. Not to mention you indicate scope with indentation, why repeat yourself with braces?
Repetition can also have practical benefits: parsing by a program is easier by keeping the 'void', for example.
(However, I still strongly agree with you on prefering "var name = new Type()" over "Type name = new Type()".)
It's a bad thing. This very topic was mentioned in Google's Go language Techtalk.
Albert Einstein said, "Everything should be made as simple as possible, but not one bit simpler."
Your complaint makes no sense in the case of a dynamically typed language, so you must intend this to refer to statically typed languages. In that case, your replacement example implicitly uses Generics (aka Template Classes), which means that any time that fun or gun is used, a new definition based upon the type of the argument. That could result in dozens of extra methods, regardless of the intent of the programmer. In particular, you're throwing away the benefit of compiler-checked type-safety for a runtime error.
If your goal was to simply pass through the argument without checking its type, then the correct type would be Object not T.
Type declarations are intended to make the programmer's life simpler, by catching errors at compile-time, instead of failing at runtime. If you have an overly complex type definition, then you probably don't understand your data. In your example, I would have suggested adding fun and gun to MyClass, instead of defining them separately. If fun and gun don't apply to all possible template types, then they should be defined in an explicit subclass, not as separate functions that take a templated class argument.
Generics exist as a way to wrap behavior around more specific objects. List, Queue, Stack, these are fine reasons for Generics, but at the end of the day, the only thing you should be doing with a bare Generic is creating an instance of it, and calling methods on it. If you really feel the need to do more than that with a Generic, then you probably need to embed your Generic class as an instance object in a wrapper class, one that defines the behaviors you need. You do this for the same reason that you embed primitives into a class: because by themselves, numbers and strings do not convey semantic information about their contents.
Example:
What semantic information does List convey? Just that you're working with multiple triples of integers. On the other hand, List, where a color has 3 integers (red, blue, green) with bounded values (0-255) conveys the intent that you're working with multiple Colors, but provides no hint as to whether the List is ordered, allows duplicates, or any other information about the Colors. Finally a Palette can add those semantics for you: a Palette has a name, contains multiple Colors, but no duplicates, and order isn't important.
This has gotten a bit far afield from the original question, but what it means to me is that DRY (Don't Repeat Yourself) means specifying information once, but that specification should be as precise as is necessary.
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.