tiennm99/styleguide
1
0
Fork 0
mirror of https://github.com/tiennm99/styleguide.git synced 2026-08-05 18:25:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update C++ style guide to 3.274:

Browse Source 
- Change formatting rules of braced initializers.
 - Permit use of constexpr and allow constexpr global variables.
 - Allow all C++11 features except for those that are specifically banned.
 - Fix/add C99 format specifiers for ptrdiff_t and ssize_t.
 - Add lambda expressions to the list of explicitly banned C++11 features.
 - Relax "return type is always on the same line as the function name" rule.
 - Allow unique_ptr, discourage ownership transfer. Allow noncopyable std::move.
 - Allow system-specific includes after other includes.
 - Add boost/math/distributions to the set of permitted Boost libraries.

Update Objective-C style guide to 2.59:
 - Use instancetype as return type for example init methods.
 - Remove invalid +stringWithInt: call.
 - Remove reference to pre-Objective-C 2.0 declaration requirements.
 - Remove reference to Objective-C exception macros.
 - Remove reference to informal protocols as an alternative to optional methods.
 - Class headers should include comments documenting non-trivial interfaces.
 - Don't specify that blocks are preferable to methods as callbacks.
 - Specify "strong" and "weak" as comments for non-Objective-C pointers.
 - Replace improper reference to ownership of a retained object.
 - Clarify some aspects of method ordering rules.
 - Prefixes are required for shared code and optional for applications.
 - Clarify that nil pointers are safe as receivers, not necessarily parameters.
 - Clarify that delegate pointers should typically be zeroing weak pointers.
 - Allow a 100-column limit, except for projects that choose to use 80.

Update Python style guide to 2.59:
 - Add more examples of bad code to the default arguments section.
 - Allow ''' when ' is used as the single quote within a file.
 - Remove references to pychecker. Recommend pylint.
 - Add more examples to the indentation section.

Update JavaScript style guide to 2.93:
 - Add @nocompile.
 - Fix a few typos.
 - When wrapping lines, indent more deeply for child expressions.
 - Document that @const can be used on a constructor.
 - Update eval section to discourage using eval for RPC.
 - Update an example to avoid encouraging using numbers as booleans.
 - Allow for no indentation of @desc jsdoc tags.
 - Add @public discussion.

Update shell style guide to 1.26:
 - Add a section on style for case statements.

Update Common Lisp style guide to 1.23:
 - fare-matcher was superseded by optima.
 - Clarify wording regarding DYNAMIC-EXTENT.
This commit is contained in:
mark@chromium.org
2013-09-25 21:16:00 +00:00
parent d6c053f670
commit 7b24563e08
6 changed files with 1036 additions and 529 deletions
Download Patch File Download Diff File Expand all files Collapse all files
objcguide.xml
+76 -156
View File
@@ -4,7 +4,7 @@
<p align="right">
Revision 2.56
Revision 2.59
</p>
@@ -132,24 +132,20 @@ Revision 2.56
#import &lt;Foundation/Foundation.h&gt;
// A sample class demonstrating good Objective-C style. All interfaces,
// categories, and protocols (read: all top-level declarations in a header)
// MUST be commented. Comments must also be adjacent to the object they're
// documenting.
// categories, and protocols (read: all non-trivial top-level declarations
// in a header) MUST be commented. Comments must also be adjacent to the
// object they're documenting.
//
// (no blank line between this comment and the interface)
@interface Foo : NSObject {
@private
NSString *_bar;
NSString *_bam;
}
@interface Foo : NSObject
// Returns an autoreleased instance of Foo. See -initWithBar: for details
// about |bar|.
+ (id)fooWithBar:(NSString *)bar;
+ (instancetype)fooWithBar:(NSString *)bar;
// Designated initializer. |bar| is a thing that represents a thing that
// does a thing.
- (id)initWithBar:(NSString *)bar;
- (instancetype)initWithBar:(NSString *)bar;
// Gets and sets |_bar|.
- (NSString *)bar;
@@ -173,18 +169,21 @@ Revision 2.56
#import "Foo.h"
@implementation Foo
@implementation Foo {
NSString *_bar;
NSString *_foo;
}
+ (id)fooWithBar:(NSString *)bar {
+ (instancetype)fooWithBar:(NSString *)bar {
return [[[self alloc] initWithBar:bar] autorelease];
}
// Must always override super's designated initializer.
- (id)init {
- (instancetype)init {
return [self initWithBar:nil];
}
- (id)initWithBar:(NSString *)bar {
- (instancetype)initWithBar:(NSString *)bar {
if ((self = [super init])) {
_bar = [bar copy];
_bam = [[NSString alloc] initWithFormat:@"hi %d", 3];
@@ -246,29 +245,14 @@ Revision 2.56
<STYLEPOINT title="Line Length">
<SUMMARY>
Each line of text in your code should try to be at most 80 characters
long.
The maximum line length for Objective-C and Objective-C++ files is 100
columns. Projects may opt to use an 80 column limit for consistency with
the C++ style guide.
</SUMMARY>
<BODY>
<p>
Strive to keep your code within 80 columns. We realize that Objective C
is a verbose language and in some cases it may be more readable to
extend slightly beyond 80 columns, but this should definitely be the
exception and not commonplace.
</p>
<p>
If a reviewer asks that you reformat a line because they feel it can be
fit in 80 columns and still be readable, you should do so.
</p>
<p>
We recognize that this rule is controversial, but so much existing
code already adheres to it, and we feel that consistency is
important.
</p>
<p>
You can make violations easier to spot in Xcode by going to <i>Xcode
&gt; Preferences &gt; Text Editing &gt; Show page guide</i>.
You can make violations easier to spot by enabling <i>Preferences &gt;
Text Editing &gt; Page guide at column: 100</i> in Xcode.
</p>
</BODY>
</STYLEPOINT>
@@ -445,9 +429,7 @@ Revision 2.56
<STYLEPOINT title="Blocks">
<SUMMARY>
Blocks are preferred to the target-selector pattern when creating
callbacks, as it makes code easier to read. Code inside blocks should be
indented four spaces.
Code inside blocks should be indented four spaces.
</SUMMARY>
<BODY>
<p>
@@ -743,7 +725,7 @@ Revision 2.56
- (void)respondToSomething:(id)something {
// bridge from Cocoa through our C++ backend
_instanceVar = _backEndObject-&gt;DoSomethingPlatformSpecific();
NSString* tempString = [NSString stringWithInt:_instanceVar];
NSString* tempString = [NSString stringWithFormat:@"%d", _instanceVar];
NSLog(@"%@", tempString);
}
@end
@@ -751,7 +733,7 @@ Revision 2.56
// The platform-specific implementation of the C++ class, using
// C++ naming.
int CrossPlatformAPI::DoSomethingPlatformSpecific() {
NSString* temp_string = [NSString stringWithInt:an_instance_var_];
NSString* temp_string = [NSString stringWithFormat:@"%d", an_instance_var_];
NSLog(@"%@", temp_string);
return [temp_string intValue];
}
@@ -766,11 +748,10 @@ Revision 2.56
</SUMMARY>
<BODY>
<p>
In <em>application-level</em> code, prefixes on class names should
generally be avoided. Having every single class with same prefix
impairs readability for no benefit. When designing code to be shared
across multiple applications, prefixes are acceptable and recommended
(e.g. <code>GTMSendMessage</code>).
When designing code to be shared across multiple applications,
prefixes are acceptable and recommended (e.g. <code>GTMSendMessage</code>).
Prefixes are also recommended for classes of large applications that
depend on external libraries.
</p>
</BODY>
@@ -1038,31 +1019,25 @@ Revision 2.56
<p>
Where instance variables are pointers to Core Foundation, C++, and
other non-Objective-C objects, they should always be declared with
the __strong or __weak type modifiers to indicate which pointers are
and are not retained. Core Foundation and other non-Objective-C object
pointers require explicit memory management, even when building for
automatic reference counting or garbage collection. When the __weak
type modifier is not allowed (e.g. C++ member variables when compiled
under clang), a comment should be used instead.
</p>
<p>
Be mindful that support for automatic C++ objects encapsulated in
Objective-C objects is disabled by default, as described <a href="http://chanson.livejournal.com/154253.html">
here</a>.
<code>strong</code> and <code>weak</code> comments to indicate which
pointers are and are not retained. Core Foundation and other
non-Objective-C object pointers require explicit memory management,
even when building for automatic reference counting or garbage
collection.
</p>
<p>
Examples of strong and weak declarations:
<CODE_SNIPPET>
@interface MyDelegate : NSObject {
@private
IBOutlet NSButton *_okButton; // normal NSControl; implicitly weak on Mac only
IBOutlet NSButton *_okButton; // Normal NSControl; implicitly weak on Mac only
AnObjcObject* _doohickey; // my doohickey
__weak MyObjcParent *_parent; // so we can send msgs back (owns me)
AnObjcObject* _doohickey; // My doohickey
__weak MyObjcParent *_parent; // So we can send msgs back (owns me)
// non-NSObject pointers...
__strong CWackyCPPClass *_wacky; // some cross-platform object
__strong CFDictionaryRef *_dict;
CWackyCPPClass *_wacky; // Strong, some cross-platform object
CFDictionaryRef *_dict; // Strong
}
@property(strong, nonatomic) NSString *doohickey;
@property(weak, nonatomic) NSString *parent;
@@ -1085,8 +1060,9 @@ Revision 2.56
<STYLEPOINT title="Instance Variables In Headers Should Be @private">
<SUMMARY>
Instance variables should be marked <code>@private</code> when they are
declared in a header file.
Instance variables should typically be declared in implementation files
or auto-synthesized by properties. When ivars are declared in a header
file, they should be marked <code>@private</code>.
</SUMMARY>
<BODY>
<CODE_SNIPPET>
@@ -1094,9 +1070,6 @@ Revision 2.56
@private
id _myInstanceVariable;
}
// public accessors, setter takes ownership
- (id)myInstanceVariable;
- (void)setMyInstanceVariable:(id)theVar;
@end
</CODE_SNIPPET>
</BODY>
@@ -1139,11 +1112,16 @@ Revision 2.56
<code>@implementation</code>.
</SUMMARY>
<BODY>
This commonly applies (but is not limited) to the <code>init...</code>,
<code>copyWithZone:</code>, and <code>dealloc</code> methods.
<code>init...</code> methods should be grouped together, followed by
the <code>copyWithZone:</code> method, and finally the
<code>dealloc</code> method.
<p>
This commonly applies (but is not limited) to the <code>init...</code>,
<code>copyWithZone:</code>, and <code>dealloc</code> methods.
<code>init...</code> methods should be grouped together, followed by
other <code>NSObject</code> methods.
</p>
<p>
Convenience class methods for creating instances may precede the
<code>NSObject</code> methods.
</p>
</BODY>
</STYLEPOINT>
@@ -1201,7 +1179,7 @@ Revision 2.56
- (NSString *)doSomethingWithDelegate; // Declare private method
@end
@implementation GTMFoo(PrivateDelegateHandling)
@implementation GTMFoo (PrivateDelegateHandling)
...
- (NSString *)doSomethingWithDelegate {
// Implement this method
@@ -1209,14 +1187,6 @@ Revision 2.56
...
@end
</CODE_SNIPPET>
<p>
Before Objective-C 2.0, if you declare a method in the private
<code>@interface</code>, but forget to implement it in the main
<code>@implementation</code>, the compiler will <i>not</i> object.
(This is because you don't implement these private methods in a
separate category.) The solution is to put the functions within
an <code>@implementation</code> that specifies the category.
</p>
<p>
If you are using Objective-C 2.0, you should instead declare your
private category using a <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_5.html#">class
@@ -1387,7 +1357,7 @@ Revision 2.56
accessors.
</p>
<CODE_SNIPPET>
- (id)init {
- (instancetype)init {
self = [super init];
if (self) {
_bar = [[NSMutableString alloc] init]; // good
@@ -1401,7 +1371,7 @@ Revision 2.56
}
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
- (id)init {
- (instancetype)init {
self = [super init];
if (self) {
self.bar = [NSMutableString string]; // avoid
@@ -1475,62 +1445,6 @@ Revision 2.56
you do use them please document exactly which methods you expect to
throw.
</p>
<p>
Do not use the <code>NS_DURING</code>, <code>NS_HANDLER</code>,
<code>NS_ENDHANDLER</code>, <code>NS_VALUERETURN</code> and
<code>NS_VOIDRETURN</code> macros unless you are writing code that
needs to run on Mac OS X 10.2 or before.
</p>
<p>
Also be aware when writing Objective-C++ code that stack based objects
are <b>not</b> cleaned up when you throw an Objective-C exception.
Example:
</p>
<CODE_SNIPPET>
class exceptiontest {
public:
exceptiontest() { NSLog(@"Created"); }
~exceptiontest() { NSLog(@"Destroyed"); }
};
void foo() {
exceptiontest a;
NSException *exception = [NSException exceptionWithName:@"foo"
reason:@"bar"
userInfo:nil];
@throw exception;
}
int main(int argc, char *argv[]) {
GMAutoreleasePool pool;
@try {
foo();
}
@catch(NSException *ex) {
NSLog(@"exception raised");
}
return 0;
}
</CODE_SNIPPET>
<p>
will give you:
</p>
<CODE_SNIPPET>
2006-09-28 12:34:29.244 exceptiontest[23661] Created
2006-09-28 12:34:29.244 exceptiontest[23661] exception raised
</CODE_SNIPPET>
<p>
Note that the destructor for <i>a</i> never got called. This is a
major concern for stack based smartptrs such as
<code>shared_ptr</code> and <code>linked_ptr</code>, as well as any
STL objects that you may want to use. Therefore it pains us to say
that if you must use exceptions in your Objective-C++ code, use C++
exceptions whenever possible. You should never re-throw an Objective-C
exception, nor are stack based C++ objects (such as
<code>std::string</code>, <code>std::vector</code> etc.) allowed in
the body of any <code>@try</code>, <code>@catch</code>, or
<code>@finally</code> blocks.
</p>
</BODY>
</STYLEPOINT>
@@ -1541,19 +1455,24 @@ Revision 2.56
</SUMMARY>
<BODY>
<p>
Use <code>nil</code> checks for logic flow of the application, not for
crash prevention. Sending a message to a <code>nil</code> object is
handled by the Objective-C runtime. If the method has no return
result, you're good to go. However if there is one, there may be
differences based on runtime architecture, return size, and OS X
version (see <a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocObjectsClasses.html#//apple_ref/doc/uid/TP30001163-CH11-SW7">Apple's
documentation</a> for specifics).
Use <code>nil</code> pointer checks for logic flow of the application,
not for preventing crashes when sending messages. With current compilers
(<a href="http://www.sealiesoftware.com/blog/archive/2012/2/29/objc_explain_return_value_of_message_to_nil.html">
as of LLVM 3.0/Xcode 4.2</a>), sending a message to <code>nil</code>
reliably returns nil as a pointer, zero as an integer or floating-point
value, structs initialized to 0, and <code>_Complex</code> values equal
to {0, 0}.
</p>
<p>
Note that this is very different from checking C/C++ pointers against
<code>NULL</code>, which the runtime does not handle and will cause
your application to crash. You still need to make sure you do not
dereference a <code>NULL</code> pointer.
Note that this applies to <code>nil</code> as a message target, not as
a parameter value. Individual methods may or may not safely handle
<code>nil</code> parameter values.
</p>
<p>
Note too that this is distinct from checking C/C++ pointers and block
pointers against <code>NULL</code>, which the runtime does not handle
and will cause your application to crash. You still need to make sure
you do not dereference a <code>NULL</code> pointer.
</p>
</BODY>
</STYLEPOINT>
@@ -1677,7 +1596,7 @@ Revision 2.56
@implementation MyClass
@synthesize name = _name;
- (id)init {
- (instancetype)init {
...
}
@end
@@ -1867,11 +1786,12 @@ Revision 2.56
<STYLEPOINT title="Delegate Pattern">
<SUMMARY>
Delegate objects should not be retained.
Delegate objects should not be retained when doing so would create
a retain cycle.
</SUMMARY>
<BODY>
<p>
A class that implements the delegate pattern should:
A class that implements the delegate pattern should typically:
<ol>
<li>
Have an instance variable named <var>_delegate</var> to reference
@@ -1882,7 +1802,9 @@ Revision 2.56
and <code>setDelegate:</code>.
</li>
<li>
The <var>_delegate</var> object should <b>not</b> be retained.
The <var>_delegate</var> object should be weak if the class
is typically retained by its delegate, such that a strong delegate
would create a retain cycle.
</li>
</ol>
</p>
@@ -1915,8 +1837,6 @@ Revision 2.56
<li>
Define callback APIs with <code>@protocol</code>, using
<code>@optional</code> if not all the methods are required.
(Exception: when using Objective-C 1.0, <code>@optional</code> isn't
available, so use a category to define an "informal protocol".)
</li>
</ul>
</p>
@@ -1951,7 +1871,7 @@ Revision 2.56
<HR/>
<p align="right">
Revision 2.56
Revision 2.59
</p>