Convention for code organization for Mesa

[rht]

In #1994 (comment) I objected to @Corvince's choice of having 1 file per class. This is not the standard convention in Python. To reply on #1994 (comment),

I think code organisation and language choice are orthogonal to each other, one shouldn't depend on the other. There have been historical reasons for keeping the number of files small, but if you look at modern libraries they tend to spread out their features into many small files and/or group their files per feature.

Citation needed. On the contrary, Java had, since the early days, organized based on 1 file/class. So I don't see how it was a limitation in the early days until Python developers decided to use Java convention.

What I find makes sense is point 2 and 3 of #1994 (comment). In a way, it's a 2 layer organization: files, and then classes. The 400 LOC shouldn't be a hard requirement. But, beyond 1k LOC would make sense for the split.

For reading:

1. PEP8
2. The Hitchhiker's Guide to Python on structuring your project -- this contains Kenneth Reiz's example repo, which organizes based on themes instead of 1 file per class/function
3. https://guicommits.com/organize-python-code-like-a-pro/ -- said "Python is different from languages like C# or Java where they enforce you to have classes named after the file they live in."
4. Dagster's guide for structuring Python projects -- they recommend to group the files based on modules/namespaces

[Corvince]

Just for reference, I do not advocate for having strictly one class per file. I didn't even do it in the PR. My comment was just meant in response to the question of how to split the file. Ending up with (mostly) one class per file was just incidently. I am used to this from my component-based frontend development (although I am not using classes there). But mesa isn't a frontend project.

What I am advocating for is organizing files by feature. So each distinctive and independent feature should reside in its own file.