proposal: package and file organisation

[Hucaru]

Problem

Packages that build up a large list of files can become rather cumbersome to work with. For example an entity package for a game server could start to become frustrating to navigate after enough entities are created e.g.:

|---> entity
      |---> character.go
      |---> chat.go
      |---> monster.go
      |---> attack.go
      |---> map.go
      |---> item.go
      |---> drop.go
      |---> characterPacket.go
      |---> chatPacket.go
      |---> monsterPacket.go
      |---> attackPacket.go
      |---> mapPacket.go
      |---> itemPacket.go
      |---> dropPacket.go
      |---> ....

As more entities are created it becomes exceedingly frustrating to find a file/struct/function of interest.

Proposal

Allow the use of folders within a package starting with "__" or "_" to retain the parent package's 'namespace'. The above file layout could be turned into:

|---> entity
      |---> character.go
      |---> chat.go
      |---> monster.go
      |---> attack.go
      |---> map.go
      |---> item.go
      |---> drop.go
      |---> ....
            |---> __packet
                  |---> characterPacket.go
                  |---> chatPacket.go
                  |---> monsterPacket.go
                  |---> attackPacket.go
                  |---> mapPacket.go
                  |---> itemPacket.go
                  |---> dropPacket.go
                  |---> ....

Since the files under the __packet folder are still part of the entity package they are able to use the data structures and functions stored in the parent folder and the parent folder files are able to call the functions in the __packet folder without causing cyclical dependency issues.

[kardianos]

May I suggest you put more code in each file? How long are these files? Typical go source files 100 to 1000 lines long with many types.

[networkimprov]

The difficulty of navigating a package with many source files has come up before.
In #27876 @yjiangnan reported:

when reading Go code of others [esp. on Github], names undeclared in the current file often come up ... Those names ... declared in another file in the package, would be much more easily understood [if their origin were available].

In that issue, I suggested letting go/doc output a "package internals manifest" -- essentially a human-readable index of identifiers from the package, with source file and line number for each.

Perhaps I should file a separate proposal along those lines?

[agnivade]

Isn't this solved with an IDE and using the corresponding jump-to-function or jump-to-struct feature ? With just a couple of keystrokes, I can go to any func/method/struct I want without looking for anything else.

I think is up to the user to decide when to split code into separate files or include them in a single one. And it is the IDE's job to help the user in finding the appropriate code.

[Hucaru]

@agnivade this would create a somewhat unreasonable overhead on github projects, as you would have to clone every repo you wanted to inspect.

Being able to group files in a package using a folder (beginning with __) would provide a non intrusive way of organising files allowing anyone irrespective of their development/viewing environment to navigate larger packages more easily.

@networkimprov that sounds like an interesting idea. However, I don't think it quite solves the issue of navigating large packages (especially on github) in an intuitive manner.

[ianthehat]

I am not sure what this adds over just prefixing the file names instead of putting them in a sub-folder.
For instance:

|---> entity
      |---> character.go
      |---> chat.go
      |---> monster.go
      |---> attack.go
      |---> map.go
      |---> item.go
      |---> drop.go
      |---> packet_character.go
      |---> packet_chat.go
      |---> packet_monster.go
      |---> packet_attack.go
      |---> packet_map.go
      |---> packet_item.go
      |---> packet_drop.go
      |---> ....

provides the same kind of "grouping" the folder does, but would be a lot less hassle to deal with, does not require any new rules, and far more importantly would not break all existing tooling.

[Hucaru]

@ianthehat whilst I disagree somewhat to just using filenames I do agree that the effort to add this in to the current tooling is probably not worth the benefit it might provide as it would only be used sparingly I imagine.