Comments With Cited References

A while back I got into the habit of adding links to any source code that I copy from the web. It's a small addition but it's helped me a lot when I need to go back and fix bugs long after I've forgotten what I did or why.

// From:
extension Data {
    /// Create hexadecimal string representation of Data object.
    /// - returns: String representation of this Data object.
    func hexadecimal() -> String {
        return map { String(format: "%02x", $0) }
            .joined(separator: "")

This technique is also really useful if you encounter unsupported or buggy behavior in some framework or library and you write a weird workaround or unconventional solution. In those cases I don't just document that it is a workaround, I try to link to a place that explains or tracks the bug (like the GitHub Issue or Stack Overflow page).

switch identifier {
case "SpecialWaitStep", "OtherSpecialWaitStep":
    // Wait steps aren't backward navigable.
    return nil
    return getStep("...")

This way if anyone (future me included) needs to go back to fix that section of code, they'll at least know why that hack is there.1

1. Hell, maybe by then the issue has been solved and they can even remove your hacky code.

Filed under: code, links,
Other Links: RSS Feed, JSON Feed, Status Page →