Coding Style Guide - Githubissues

felix-schwarz commented 5 years ago

This is a loose collection of code style rules that contributions to this project should follow:

SwiftLint

The rules laid down in .swiftlint.yml apply and code submitted to the project should not raise any SwiftLint warnings.

Only exception: limited usage of TODOs are acceptable in cases

where functionality can't be implemented because it requires work in another branch or the SDK to finish first.
where the priority to wrap up work on a PR and get it merged outweighs the priority to get a minor detail done 100% right. In those cases, a TODO should document there's more to be done, so it can be taken care of in a later PR.

File Names

Files containing a definition of type, for example MyType shall be named MyType.swift. Files containing type extension shall be named as follows: <TypeName>+<ExtensionDescription>.swift (for example UIView+Animations.swift).

Naming Conventions

Type names / protocol names shall use PascalCase, e.g. SomeClass. Variables, constants and function names shall use camelCase, e.g. myVariable.

Variable names should be expressive so the code is easier to read. For example tableViewController should be used instead of tableVC, tvc or vc.

Constants

Constant declarations shall start with the keyword let. To declare a type related constant, use static let.

Private APIs

The use of private API is not allowed.

Granularity

The code should follow these granularity rules:

avoid duplication of code by moving identical or near-identical code that's used in multiple places into functions/methods
if a method/function is only called from a single place, it's often a better choice to inline that code in the place of the method/function call
the use of constants should follow the same rule. If f.ex. a string constant is only used in the getter/setter implementation that's only a couple of lines apart, it can be more appropriate to directly inline that string than to put it into a constant.

The goal of these rules is to keep the code from becoming too fragmented to easily comprehend. If f.ex. a method is the only caller of another method, which is the only user of a constant, anyone who wants to work on or understand the code would need to look in up to three different places and put the picture together. This should be avoided.

Modularity

Whenever possible, the implementation of a class should be as self-contained as possible. It's internal logic shouldn't be distributed across several classes unless there's a good reason for it.

Indentation

This project uses tabs so that different tab widths don't lead to inconsistent alignment of code throughout source files.

References to OCCore

Code in ios-app should avoid strong references to instances of OCCore for long-lived objects like views or view controllers. Instead, wherever possible, use weak references.

The lifecycle of OCCore should be solely managed by OCCoreManager, which holds a strong reference until all requests for cores have been followed by a return. At that point, it releases its reference to OCCore, expecting that it also frees all of its resources.

Copyright / License

Every file should carry the standard copyright / license notice:

/*
 * Copyright (C) 2018, ownCloud GmbH.
 *
 * This code is covered by the GNU Public License Version 3.
 *
 * For distribution utilizing Apple mechanisms please see https://owncloud.org/contribute/iOS-license-exception/
 * You should have received a copy of this license along with this program. If not, see <http://www.gnu.org/licenses/gpl-3.0.en.html>.
 *
 */

Git branching model and workflow

This project follows the standard OneFlow model.

References

Swift ORG API Design Guidelines Google's Swift Styleguide

michaelstingl commented 5 years ago

I like the CONTRIBUTING.md from the unofficial WWDC app for macOS https://wwdc.io