File Organization isn't consistent with most Swift code out there

[dalemyers]

What convention is being referenced?

The ordering in a file suggests most "important" to least "important", where how important it is is proportional to its visibility. i.e. public is the most important and private is the least important. This gives an interesting example of a code like this (trimmed here):

public class House {

    // public functions
    public init {
    // ...
    }

    private var size: Int = 0

}

You can see that the instance variable is at the bottom of the definition.

How do you propose this convention could be improved? Please provide rationale and examples if possible.

This rule is overly broad and not particularly helpful. Convention across the last several decades of programming has us put instance variables at the top of the file usually. We should correct to allow for this at the very least.

I'd also argue that a small private helper method makes more sense to be located next to the public method that uses it, rather than at the other end of the file.

[cy255]

The rationale behind this convention is that "Ordering file contents by access level ensures that the entities with the least restrictive access level get the most visibility, which are likely the components that developers interact with the most." Following this rule yes private properties are at the bottom of the definition, but it's not necessarily a bad thing to have a convention different from "what it has always been". Swift itself has a lot of uniqueness and its access levels are one of them. I would like to know other people's thoughts on this as well. @anandrajeswaran @markavitale

[anandrajeswaran]

These are good questions. The specific examples are usually the easiest way to talk about these and you provided some great examples. Some of my thoughts on those:

• Instance variables at the top: Swift is a bit different than other languages in that instance variables aren't just allocated storage. With computed properties, didSets/willSets, and other power Swift has added around variables there isn't much of a distinction between instance variables and methods. From that perspective I think the convention makes sense in that it brings a standardized way of thinking where Swift adds some complexity relative to preexisting patterns.
• A small private helper living close to its usage is a really good case, but I think in cases where it's super confusing the real core issue may just be having too much stuff in one file? And the idea that something is split into a separate func almost always in practice means it's called from multiple places so thus can't have that much affinity with a single call. My personal bias is I've found a great amount of joy from following this pattern in ObjC for years and haven't seen the "disjointed helper method" issue in practice.

[dalemyers]

@cy255 I'd love to know more about this "visibility" aspect of code being at the top of files. Personally, it's not something I'm concerned with since I'm either searching for what I want, or using the navigator drop down. I don't ever scroll through files to find what I'm looking for. Is that not the case for most? Or have I misunderstood what you mean?

[cy255]

I think every developer navigates Swift files differently. In some scenarios where the file is not big (or have many // MARK comments), scrolling is still quite a popular way to navigate a file. The most visible functionalities are usually the ones that developers care about the most. In addition, we've found that enforcing order by "visibility" does help with understanding visibility better.