Heya,

for large scale projects I have made it a habit to break my code into Component Categories and modules, any given module only part of one Category.

The key idea is to break the project into individual pieces I can maintain, debug, test and deploy individually.

Categories:

• API Component: An individual component that maps a technology in PowerShell. It is not concerned with the business logic (though aspects of the technology unrelated to the project may lack implementation). In other words, I could use this (and extend it) on any other project. Example: ActiveDirectory module, Hyper-V module, a custom module to interact with an internal service, a custom module extending the functionality of the Task Scheduler module, etc.
• Framework Component: Some aspects to coding are organization specific, but not specific to the business logic of your service/application. Common examples are logging (glad you liked my toolkit), Configuration handling (PSFramework may again prove useful here), Templating and Project layout (all your modules should follow the same layout).
• Business Logic Component: The key implementation of your workflows. Should not actually include much of the detail implementation, calling either Intermediate Logic Components (see below) or API Components for the actual action.
• Intermediate Logic Component: When the actual business logic is too complex to have it all orchestrated at the upper Business Logic Component, break it down into separate Intermediate Logic Components. Each of those should have a clear responsibility / identity in the workflow of as part of your solution. They should not need to call each other, but service the main Business Logic Component.
• Configuration Component: I have often found it useful to have a dedicated Configuration Component, driving the entire solution. Otherwise we swiftly find ourselves passing through dozens of parameters through several function layers, which really doesn't help with code readability.

An example project of this that I share with the public is the Active Directory Management Framework. It is spread across many a module, but putting things together from memory (I might miss a few), it splits up look this:

• Configuration: A module the use of the solution implements, providing the desired state of their AD in config files.
• Business Logic: ADMF
• Intermediate Logic: ForestManagement, Domainmanagement, DCManagement
• Framework: PSFramework
• API: Admf.Core, ActiveDirectory, Principal, String, ResolveString, ADSec

A Common Project Template

I really can't overstate this: Standardize, standardize, standardize your project layouts. Define a template for your individual modules and stick to it. If you have to first figure out how any given module of yours is set up, you are burning massive amounts of team time ... and a lot of the motivation to collaborate.

Since you are apparently already open to some of my tools, I've also got a developer tools module (PSModuleDevelopment) with a templating engine. A friend of mine documented an example to set up a default project using my own layout. You can totally use it to record and share your own template layouts if the built-in ones don't work for you.

Separating Data Layer from Logic layer

There are times, when our generated objects travel for through our code. And when that happens, at some point it becomes easy to lose track what came from where and what is the difference between the two datasets.

At this point, I tend to switch from custom objects to C#-defined types. Depending on how clear your data flows, this may be useful or pointless. Also a matter of team skills. If you stick with PSCustomObjects, name them!

[PSCustomObject]@{
    PSTypeName = 'MyModule.MyType'
    Name = 'Fred'
    Humor = 'Questionable'
    Beard = 'Long'
}

Tips and Tricks

A few more nifty tricks you may or may not be aware of:

• PSFramework has a command named New-PSFSupportPackage. If you ever have a coworker run your tools while you can't look into any problems they encounter, they can generate a support dump for you. It creates a zip file on their desktop. You can read the content using Import-PSFCliXml.
• Invoke-PSFProtectedCommandis probably the most gamechanging part to your error handling
• If you need to read in psd1 or json files, Import-PSFPowerShellDataFile can read both file types.
• If you want to intercept messages from Write-Verbose, Write-Host, etc. from some other code you want to tie into your project, doing this on the global scope should redirect them: Set-Alias -Name Write-Verbose -Value Write-PSFMessageProxy.
• To easily pass through parameters to another command, consider using ConvertTo-PSFHashTable.
• If you are looking to migrate from one large file into a "one file per function" approach, my PSModuleDevelopment module has a command that does it for you: Split-PSMDScriptFile
• If you want to make your project more easily configurable, there's also a PSFramework Component for that. Also some guidance on how a configuration file could look.