Swift Coding Standards
do {
try query.setCount(rc)
let function = try ModbusConnection.Function.fromQuery(query)
if shouldProcessRequest(function) {
logger.info("Processing request: \(function)")
try delegate.modbusServerHandleRequest(self, function)
} else {
logger.info("Received request: \(function)")
}
if modbus_reply(conn.context, query.raw, rc, mapping) == -1 {
throw ModbusError.cLibModbusError(code: errno, method: "modbus_reply")
}
} catch ModbusError.modbusException(let exception) {
// Note: we intentionally do not log this since it is just being reported
// back to the master, hence none of its information is lost.
modbus_reply_exception(conn.context, query.raw, exception.rawValue)
} catch {
// Note: we log this since it will be translated to a .negativeAcknowledge
// before being reported to the master, and we may need to go back
// in the logs and trace the problem.
logger.error("Could not handle request: \(error.localizedDescription)")
modbus_reply_exception(conn.context,
query.raw,
ModbusReplyException.negativeAcknowledge.rawValue)
}
General Coding Principles
- Favour reliability and readability over strict formatting guidelines, but if you choose to break one of our guidelines you must be prepared to justify your decision.
- Follow Programming by Contract patterns. Primarily use the precondition method of the standard library.
- Write unit tests that cover your code. Your code must pass the unit tests before your pull requests will be accepted. Use the XCTest framework for your tests.
- Follow the Swift 5 standard.
- Document the public portion of your API using an Xcode compatible markup.
- Do not comment the obvious. Other than the public API comments mentioned above, comments should not be necessary to understand what the code does. However, they should be used to describe why something is done. Consider the sample code shown on this page (which comes from the
KSSModbusproject). The comments when catching the errors are not saying "we are logging" or "we are not logging" as that is obvious. Instead they say why we are logging in one case and not the other. This helps ensure that a future programmer looking at the code does not erroneously think "we are missing a logging statement." - Do not use newlines liberally. In particular, do not use them to make your code "double spaced." Newlines should be used to draw the eye to logically grouped sections of the code.
- Eliminate all compiler warnings.
Specific Coding Guidelines
For the most part, follow the default settings that Xcode provides. Don’t fight the tools!
The following documents provide more specific coding guidelines. If you choose to write code that breaks a recommended guideline, be prepared to justify your decision.
In addition, please use the following:
- Keep lines to no more than 95 characters in length.1
- Keep methods and blocks to no more than 50 lines in length.2
- Use a single underscore to prefix the names of any method or property that should be treated as private but that cannot actually be made private.
1. Our code reviewers should be able to view two files side by side in a 12pt font on a reasonably sized desk monitor.
2. Developers should be able to see an entire block at once in a 12pt font on a laptop screen.