My notes on writing method step documentation
Introduction
- Software is complex.
- Some methods use many levels of closures, helpers, etc.
- Instead of putting the responsibility of reasoning on the reader, why not write step documentation in the method doc.
- This way you don’t have to jump through a lot of files and methods and in the process lose your barrings
- The reader can easily just derive the context from reading the steps in the method doc
/**
* Call remote service for the stockPrice
* 1. Calls remote api
* 2. Cleans up the result a bit
* 3. Combines the result a bit
* 4. Splits the result, because we only need the first part
* 5. Return the result we are looking for
*/
func getStockPrice(url: String, stockName: String, onComplete: (String?) -> Void) {
networkCall(url: url, stockName: stockName) { result
let processedResult = process(result)
let combinedResult = combine(processedResult)
let split = split(combinedResult)
onComplete(split.first)
}
}