I am trying to explain different coding styles to some individuals I am training. The only issue is, I don't know the semantic name for these 2 styles of programming.
For example, I know that this is GNU:
class Object
{
// statements
}
I need help defining these two:
class Object {
}
and this variable naming style:
string sNotHungarianNotation = "";
string but_this_style = "";
where the variables have underscores between them.
I'd appreciate the help. I've looked at several different sources but could not come to a cogent answer.
As far as names for brace positioning, if you really care about them, Indent style on Wikipedia has far more info than you'll probably ever care about. That said, your two examples are typically referred to as Allman style and K&R style, respectively.
For variable naming, your first example is typically called camelCase and the second version is often referred to as snake_case.
Related
I'm beginning development on a nontrivial application for which we're considering GraphQL. When working on the initial draft of our schema, I've become a bit paralyzed trying to establish naming conventions that will scale as the product matures. I would really appreciate some insight from anyone who has had to grow a schema and run into, or successfully avoided dead ends or inconsistencies:
Is it generally useful/idiomatic to keep the name "Interface" in the name of an interface? For example, would Profile or ProfileInterface be preferable in a large app?
interface ProfileInterface {
# fields here...
}
type UserProfile implements ProfileInterface {
# implemented fields here...
}
Is it common to specify single-enum values as "constants"?
enum GeoJSONFeatureTypeConstant {
feature
}
interface GeoJSONFeatureInterface {
id: ID
type: GeoJSONFeatureTypeConstant!
geometry: GeoJSONGeometryInterface!
properties: GeoJSONProperties
}
Is it best practice to declare all-or-nothing objects as scalar or type, and where is the line drawn between the two? Imagine a Point type that is would typically be represented as an array [x,y]; which would be more idiomadic?
scalar Point
type Point {
x: Float
y: Float
}
Any other best-practices specifically related to naming conventions or type declarations in GraphQL that would be difficult to know without experience.
Thanks in advance!
This question hasn't gained the momentum I would have liked, so I'm going to start posting useful snippets as I find them, which may evolve into an answer of sorts.
Naming input types with Input on the end is a useful convention,
because you will often want both an input type and an output type that
are slightly different for a single conceptual object.
http://graphql.org/graphql-js/mutations-and-input-types/
I pondered about these same questions and I hope this will be helpful to you.
1. I don't believe that appending Interface at the end of every interface is idiomatic. It is much better to have a descriptive name instead. Consider the example provided in the GraphQL Specification relating to Interfaces. They don't append Interface to any of their types.
2. Enums are only advantageous when there are multiple related values. I don't see how including type is helpful when there is only one possible value. Enum values are also named with all caps and underscores per the GraphQL Specification relating to Enums.
3. If you decided to implement a scalar type then it is up to you to validate the field. In this specific case, providing Point as a type makes the most sense as a Point could be 2-D or 3-D. Defining it as a type is more declarative.
Values such as Date, Email and Url are common examples for scalar types. They provide semantic value and clients will know what to expect from these fields.
Here's the relevant section for custom scalars.
Here's an example.
4. You will find this article by Lee Byron helpful.
I found this graphql API design tutorial from Shopify some time ago. I think there is no explicit chapter but best practice w.r.t. naming convention spread across the tutorial.
I have an angular 1.4 project on typescript, the project is getting bigger and bigger and our team is really tired of interfaces that we have declared (so that all objects are typed, in comparison to any)
I'm asking if this is a good idea or not? I chose typescript because I wanted to have a typed project, should I drop the interfaces or not?
You can get by without using interfaces and going with any, but in the long term you are probably going to regret it. If your team is sick of the interfaces you've created, I would put time in fixing those instead of abandoning them. There is a significant argument around if typed languages reduce the number of errors found in code. Personally, I think they do.
What I've found with typed languages is that it helps remove stupid mistakes we all make, and this clears up our time to focus on actual logic problems in code. Not everyone agrees with me on this, but I will always pick a type language over a non typed one, especially if the team is used to dealing with languages like Java or C#.
Interfaces can be very helpful if used properly.
If you are just doing this....
IFoo { ... }
Foo implements IFoo { ... }
Then they will not help as much as they do in other typed languages (C#/Java). Because the type checking in TypeScript is dependent upon the properties on the object and NOT on the declared type. This is because you can simply write this...
MyCtrl (foo: Foo) { ... }
//instead of
MyCtrl {foo: IFoo) { ... }
This will not hinder unit testing in any way since as stated above the type checking is based upon properties and not declarations.
There are cases when interfaces can be quite helpful, for instance a common use case is when defining an object as a parameter...
doSomething (options: ISomethingOptions) { ... }
There is no harm in creating interfaces for everything, you just need to determine what level of typing works best for your team.
I was explaining to a friend a few days ago the concept or inheritance and containers.
He has very little programming knowledge so it was really just a friendly chat.
During the conversation he came to me with a question that i just couldn't answer.
"Why cant you just have an array of the top level class, and add anything to it"
I know this is a bad idea having being told so before by someone far smarter but for the life of me i couldn't remember why.
I mean we do it all the time with inheritance.
Say we have class animal which is parent of cat and dog. If we need a container of both of these we make the array of type animal.
So lets say we didn't have that inheritance link, couldn't we just use the base object class and have everything in the one container.
No specific programming language.
Syntactically, there is no problem with this. By declaring an array of a specific type, you are giving implicit information about the contents of that array. You could well declare a contain of Object instances, but it means you lose all the type information of the original class at compile-time.
It also means that each time you get an object out of the array at runtime, the only field instances and methods you know exist are the fields/methods of Object (which arguably is a compile time problem). To use any of the fields and methods of more specific subclasses of the object, you'd have to cast.
Alternatively, to find out the specific class at runtime you'd have to use features like reflection which are overkill for the majority of cases.
When you take elements out of the container you want to have some guarantees as to what can be done with them. If all elements of the container are returned as instances of Animal (remember here that instances of Dog are also instances of Animal) then you know that they can do all the things that Animals can do (which is more things than what all Objects can do).
Maybe, we do it in programming for the same reason as in Biology? Reptiles and Whales are animals, but they are quite different.
It depends on the situation, but without context, it's definitely okay in most (if not all) object-oriented languages to have an array of a base type (that is, as long as they follow all the substitution principles) containing various instances of different derived types.
Object arrays exist in certain cases in most languages. The problem is that whenever you want to use them, you need to remember what type they were, and stay casting them or whatever.
It also makes the code very horrible to follow and even more horrible to extend, not to mention error prone.
Plant myplant = new Plant();
listOfAnimals.Add(myplant);
would work if the list is object, but you'd get a compile time error if it was Animal.
Something I see ppl define the variable like this:
b2World *_world;
b2Body *_body;
CCSprite *_ball;
instead of
b2World *world;
b2Body *body;
CCSprite *ball;
I familiar with the second one, but not the first one. So, I checked the Wikipedia about naming convention:
Names beginning with double underscore
or an underscore and a capital letter
are reserved for implementation
(compiler, standard library) and
should not be used (e.g. __reserved or
_Reserved).
So, is that any special meaning which is start with "_"?
The code I saw which using "_" to begin is here:
http://www.raywenderlich.com/457/intro-to-box2d-with-cocos2d-tutorial-bouncing-balls
The wiki page.
There's a long-standing convention among some Objective-C developers to prefix instance variables with an underscore. It can be helpful in several ways: one, it makes it easier to spot instance variables in a .m file; two, it relieves developers of having to come up with creative names for method parameters to avoid colliding with instance variable names; and three, as others have noted, it indicates that the instance variables are private, and therefore shouldn't be accessed willy nilly throughout the code.
In fact, I'd argue for avoiding accessing instance variables directly in methods other than accessors (getters and setters), -dealloc, and -init.... Not that you should never, ever use them anywhere else, but you should at least give it some thought before using an instance variable directly in other methods.
It's really really helpful, but most people don't know why, and that's a shame.
Apple uses underscores to separate the way other objects access a particular object's variables, and the way a particular object access its own variables.
Now this may sound a little bit strange, but imagine the following: You probably all recognize the following compiler warning
.h
#property (nonatomic, retain, readonly) UITableView *tableView;
.m
- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
return [self loadSomethingElseForTableView:tableView];
}
This will result in a compiler warning, because it does not know wether you reference to the local variable "tableView", or the instance variable.
Therefore, Apple recommends you to add the following to the top of your #implementation.
#synthesize tableView = _tableView;
Now, when you reference to _tableView, the compiler knows that you mean the instance variable, and not the local one.
Also, this makes it a lot easier to understand the Garbage Collection in Obj-C, and to prevent making common mistakes.
For example, when doing the following:
#property (nonatomic, retain, readonly) NSString *title;
- (id)initWithTitle:(NSString *)title {
if ((self = [super init])) {
self.title = title; // Is not possible, since it's read only.
title = title; // Is not possible, since it's the same (local) variable.
// Changing the method to initWithTitle:(NSString *)aTitle;
title = aTitle;
}
return self;
}
Now, since you do not use the default setter (actually, you can't, because it's read-only) you need to retain the variable yourself.
This is a lot easier to remember when you give every instance variable a prefix (so you know you need to retain it yourself).
So, basically, it's important to understand the difference between self.variable and (_)variable. (that is: self.variable maps to [self setVariable:...] and variable maps directly to your pointer.
Furthermore, when you add it as a private variable, like this:
#interface TSSomeObject : NSObject {
#private
NSString *_privateTitle;
}
#end
The underscore prefix isn't really necessary, unless you may encounter local variables that have the same name. Besides that, again, it's also an easy way to remind you that it's a local pointer and that you need to retain (and release) the variable when you assign it to your object.
What is wrong is to create a property with a underscore prefix, like this:
#property (nonatomic, retain) NSString *_title;
That's really wrong, and I'm not even gonna explain why ;)
So yes! You should really use underscore prefixes, it makes your code a lot easier to read, and to interpret by the compiler! In Xcode 4, Apple even added these #synthesizes to the default templates.
Usually they're used for variables that shouldn't be accessed outside the current file/module/namespace/whatever, in languages that don't support restricting access with something like a private keyword
https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingIvarsAndTypes.html#//apple_ref/doc/uid/20001284-1001757
Both by convention and recommendation in the above document, you should prefix ivars with an underscore.
Admittedly, it is in reference to explicitly set ivars for properties.
But the usage is the same, to indicate the usage of an ivar wherever it is seen.
I am however open to the possibility, that in that context, the use of an underscore prefixed ivar could signal to the user that they are doing something wrong. Meanwhile a postfixed underscore could be used for pure ivars that are meant to be accessed directly.
This blog has some good thoughts from an experienced practitioner and it recommends using prefixed underscores.
http://blog.bignerdranch.com/463-a-motivation-for-ivar-decorations/
Wether you choose to use prefixed underscores to decorate your own ivars, there is at least some evidence that some kind of decoration will help you avoid bugs. And prefix'd underscores are the most common decoration.
Apple reserves names beginning with underscore for its own private ivars and methods. In Objective-C on any Apple platform, it is recommended that you do not prefix your identifiers with an underscore.
http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html
This question already has answers here:
Closed 13 years ago.
Possible Duplicates:
Formatting of if Statements
Is there a best coding style for identations (same line, next line)?
Best way to code stackoverflow style 'questions' / 'tags' rollover buttons
public void Method {
}
or
public void Method
{
}
Besides personal preference is there any benefit of one style over another? I used to swear by the second method though now use the first style for work and personal projects.
By readability I mean imagine code in those methods - if/else etc...
Google C++ Style Guide suggests
Return type on the same line as function name, parameters on the same line if they fit.
Functions look like this:
ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
DoSomething();
...
}
WebKit Coding Style Guidelines suggests
Function definitions: place each brace on its own line.
Right:
int main()
{
...
}
Wrong:
int main() {
...
}
They suggest braces-on-same-line for everything else, though.
GNU Coding Standards suggests
It is important to put the open-brace that starts the body of a C function in column one, so that they will start a defun. Several tools look for open-braces in column one to find the beginnings of C functions. These tools will not work on code not formatted that way.
Avoid putting open-brace, open-parenthesis or open-bracket in column one when they are inside a function, so that they won't start a defun. The open-brace that starts a struct body can go in column one if you find it useful to treat that definition as a defun.
It is also important for function definitions to start the name of the function in column one. This helps people to search for function definitions, and may also help certain tools recognize them. Thus, using Standard C syntax, the format is this:
static char *
concat (char *s1, char *s2)
{
...
}
or, if you want to use traditional C syntax, format the definition like this:
static char *
concat (s1, s2) /* Name starts in column one here */
char *s1, *s2;
{ /* Open brace in column one here */
...
}
As you can see, everybody has their own opinions. Personally, I prefer the Perl-ish braces-on-same-line-except-for-else, but as long as everybody working on the code can cooperate, it really doesn't matter.
I think it is completely subjective, however, I think it is important to establish code standards for your team and have everyone use the same style. That being said I like the second one (and have made my team use it) because it seems easier to read when it is not your code.
In the old days we used to use the first style (K & R style) because screens were smaller and code was often printed onto this stuff called paper.
These days we have big screen and the second method (ANSI style) makes it easier to see if your brackets match up.
See HERE and HERE for more information.
First one is smaller in terms of number of lines (maybe that is why development -Java- books tend to use that syntax)
Second one is, IMHO easier to read as you always have two aligned brackets.
Anyway both of them are widely used, it's a matter of your personal preferences.
I use the if statement as something to reason on in this highly emotive subject.
if (cond) {
//code
}
by just asking what does the else statement look like? The logical extension of the above is:-
if (cond) {
//code
} else {
//more code
}
Is that readable? I don't think so and its just plain ugly too.
More lines is != less readable. Hence I'd go with your latter option.
Personally I find the second one more readable (aligned curlys).
Its always easiest for a team to go with the defaults, and since Visual Studio and I agree on this, thats my argument. ;-)
Your lines of code count will be considerably less with the first option. :)