How do you plan or outline a program?

I would be careful not to get too deep into object orientation and other ways of organizing code too early.

My approach is to delay organization until I'm sure I need it, refactoring as I go. I stick with a single file until it gets unwieldy. Maybe start with "hello world" (whatever that means for your app) and start coding in the main method. Extract a function after you've written the code inline and you have a block of code that works and would make sense on its own. Once you have a few functions that operate on the same data structure, then it's time to consider a class. Once you have a class, consider what functionality you've already written that belongs there.

At least, that's what I do when in doubt. Sometimes you know ahead of time the structure you want.

Edit: It's kind of hard to talk about in the abstract, though. If you're willing to post some code publicly then you could get more specific advice.

Since you are just starting out you might just want to start programming and see how well it turns out. If it really is not important, you can write absolute spaghetti code so you can get an idea where you personally need to organize.

Personally I start off by writing a skeleton of all the classes and methods I need. Then I try to write the documentation first. Then I realize as I am writing that I made logical mistakes as I was planning and rewrite everything. 😸

In general you just get better the more you work on a variety of programs. A general strategy is to get down a minimum viable product -- the base basic possible implementation of what you're trying to do. From there, it's all incremental, which is nice.

Additionally, try to think about the parts of the program which radiate outwards design wise. Typically UIs, for instance, I do last, since the core functionality will dictate what the UI has, so if you make it first, you'll probably have to change it by the end.

In terms of actual tools, I've been using Whimsical at work. It's just a nice diagram builder. Good for collaboration, though I suppose you won't use that.

Do you ever use libraries or modules that other people wrote? I've found that using a well-written library teaches you how to organize your own code even if you don't intentionally set out with that goal in mind. There are certain concepts that are well known that you start to see in other people's code and you can start to use in your own.

One of the most important concepts that helps with organizing code is called separation of concerns. It's also sometimes referred to as "separating your business logic from your display logic." The idea is that the code that displays your data is completely separate from the code that manipulates your data. This is probably the single most helpful concept I've learned when it comes to writing better code. Concepts that go along with this include loose coupling and information or data hiding. These help with making your program easier to modify and less fragile.

I'm not a skilled programmer (com-sci dropout for Information Systems, lol), and I'm pretty bad at commenting, but I don't have issues tracking my admittedly simple programs. However, the way I design a program is to think about what I need, and choose object, function and variable names that are descriptive, either in their capacity as a variable, which I assume you're already doing. Better commenting a habit I should start doing.

Basically what I've learned is do something like this:

#What the class does
class ThingClassDoes #(abbreviated name here for what it's supposed to do)
  def thingForClass() # this would be the constructor
  def thingForClass() # this would be the method, but
    # brief description of what the function does
  def functionInClass # this is the actual function, you'll generally not need a constructor)
    # brief description of what function does

If your names are meaningfu, it goes a long way, the rest is just keeping things clean and sort of having a flow to your code.

One thing to keep in mind about object-oriented programming is that you have a choice of ways to organize your functions and these choices are sometimes arbitrary. For example, let's say you have two classes, Foo and Bar, and a function that takes two arguments:

def quack(foo, bar):
   # do something

There are three places that you could put this function:

• As a method on Foo (the foo argument becomes self)
• As a method on Bar (the bar argument becomes self)
• As a standalone function. (It stays the way it is.)

Which one you choose is often a matter of taste: where do you expect to find this function? It's often useful to look at a method's arguments and consider whether you can move the method to some other class, or when looking at a standalone function, you can decide whether it should really be a method on one of its parameters.

But, you don't want to get too caught up in tidying up. This is internal organization for the benefit of you and your team and the users aren't going to care. Moving things around can be helpful, but someone who expects to find them in their old location might be confused.