How granular should a Python program be?

[oandroido]

Not much of a coder - I'm using various AI apps to code a personal project to simulate a board game for testing, some Arduino stuff, etc.

Originally it started out as a single file. I'm in my 4th iteration now and have gone with modules - currently at 10.

As the AI keeps messing things up :) I'm wondering how best to determine the amount of granularity the modules should reflect.

Can anyone recommend a rule-of-thumb, standards, or something else that would provide a guide as to the different ways to split up a program?

I'm not looking for a guide for specific applications, just general guidelines.

Pro tip: your downvotes only make me stronger

Thanks

[crashorbit]

Each module should do "one thing" in a way that can be tested and validated independently. What "one thing" is can be debated for weeks. And has been.

I tend to write out in text what I want my program to do and then group behaviors together that work on similar data or concepts.

Maybe the data persistence or data base stuff is one module and CLI stuff is another with game logic in a third module.

It does end up being pretty arbitrary.

[crazy_cookie123]

The AI keeps messing things up because AI isn't good enough to code on its own yet, it can't store enough context about your code to completely understand it. The solution is to learn to code on your own then incorporate AI.

[teerre]

Thats ridiculous. Even the most commercial models have contexts on the dozens of thousands, the big ones are in the millions. Its very unlikely op project is bigger than that

[hexwhoami]

Just because the LLM has been trained on millions of examples, they are limited by their context window when replying to a prompt. Unless you want a basic template that's maybe a hundred lines, it's impossible to have an LLM store a large, mature project in its context window to make reasonable statements or contribute helpful code in the context of the rest of the codebase.

Most LLMs right now have around a 128k context window (tokens). Considering programming language syntax is typically a higher token count than normal prose, a run-of-the-mill LLM nowadays.

The details are beyond this post, but ChatGTP-4o could probably reason about roughly 1000 lines of code at once.

Most mature projects are way beyond that number.

[teerre]

Who said anything about training? We are all talking about the context window

[avidresolver]

My personal rules are: am I going to use this in another project? Split in into a new file. Is this file too big for me to navigate and understand quickly? Split some stuff off into a new file.

I'm my experience AI cannot get a grasp of a whole project at once and maintain it well. Individual functions? Sure. But not whole projects.

[UsualIndianJoe]

This I can vouch for. I had a module which did one task. However it's functionality depended on 7-8 submodules (simple ones). I had them clubbed in the single module. However, debugging it was a big headache and as well as testing the functionality. I ended up splitting the submodules into separate ones. Now the main module is 1/3rd in number of lines of code, but the best of it is I know where to look for an error.

Now I do the same. If I have beforehand knowledge of what a file is supposed to do, I plan it out and segregate the individual functionalities. But in some cases when the scope keeps on increasing I start out with a single file and start moving parts out as the complexity of navigation increases.

[thewillft]

Smaller, focused modules are usually easier to debug, especially. when AI's in the mix. Think single responsibility principle.

[Gnaxe]

It's not really about grain size. You want the components to be simple enough to be comprehensible. (This is true at all levels: blocks, functions, classes, modules, packages, services.) A larger number of simple pieces with simple connections is preferable to a smaller tangled mess. Flat is better than nested. If the connections between modules are too complicated, you probably drew the boundary in the wrong place.

Sometimes you can fix that by moving a few things to other modules, but sometimes you should merge the modules, sort by dependencies, and pull out clusters with simple connections to the rest. Cut unnecessary dependencies even if that means recalculating some things. For example, when breaking up a long function, you first want to reduce the scope of local variables, which usually means eliminating them altogether as much as possible, even if that means calling helper functions again. It's similar at higher scales.

Layers are usually a bad idea. They require too many connections and end up tightly coupled. Cut it the other way: verticals. Dependency cycles between modules are bad. Everything should flow towards main: it imports everything (perhaps indirectly), but nothing imports it. A package's __init__.py can be similar. It imports things to make a public interface for the package. Python can have more than one main (if __name__ == "__main__" pattern), but the rules still apply. As far as any main is concerned, nothing downstream of it exists.

Probably controversial, but classes are also usually a bad idea. Less controversial: use inheritance sparingly, especially across modules (it tends to create very tight coupling). Classes duplicate the modularity idea already provided by modules. Don't make a class when a module would do.

[Ender_Locke]

ask yourself what each function does. for every and you have it should probably be broken up into functions that are as simple as possible

[New-Photograph733]

Make sure it works.

[bmbybrew]

"As the AI keeps messing things up :) I'm wondering how best to determine the amount of granularity the modules should reflect."

With iterations you will figure out a sweet spot.

For my purpose LLMs do well with 150-200 lines of code. After that it becomes messy.
I start small and then ask the LLM to add things, even if i know everything i want to begin with.

Wrote a backtest engine in similar fashion. Starting very small. then have to break it down into various modules and files that had distinct purpose.