The Rant
Can't deny Terraform has become simply essential nowadays and saved me tons of hours, but my experience working with was awful for several reasons. We are yet to see a IAC tool that's intuitive and pleasurable to work with.
Your repo will eventually become a mess as your infrastructure gets more complex even if you read the Terraform Recommended Practices, Terraform Best Practices website (which didn't help much) especially as you need to manage multiple accounts and "prod", "dev" and "qa" environments.
Refactoring it's hard. Migrating a resource from one state to another, realizing the resource would be better on a module or simply moving inside the same state. Sometimes you will need to replace a direct resource reference with a Data source or read another module output directly.
You need to learn HCL and his peculiarities and sometimes write something that was supposed to be written in another way like YAML when using the Kubernetes Provider. This CLI can help.
Some providers like the Helm Provider are too different of the standard workflow with the actual tool and gave me problems several times.
You need to follow the same boilerplate of backend.tf, outputs.tf, main.tf, variables.tf for every single small module and will be copying and pasting the same stuff a couple of times.
You can't configure relative paths for modules which soon becomes a "dot dot hell".
Having to use count for conditional resources and [count.index] when referencing them it's just weird.
Sometimes you simply can't fetch what you need using the Data Source available.
The Tips
I like to follow best practices when they make sense and the Best practices for Terraform on Google Cloud helped me a lot.
I use AWS Secrets Manager to store all my secrets instead of using .tfvars and read using a data source.
I suggest keeping Architecture Decision Records every time you need to make a decision about how to organize your code.
My folder structure
In the accounts folder I will list all my accounts my name. If you have a multi-cloud enviroment and multiple accounts for each cloud you can create folder like aws, gcp and azure inside this folder.
In the global folder I configure resources like CloudTrail and IAM which applies to all account despite of region and create a folder for each region I'm using like us-east-1 or sa-east-1.
In each region folder I create a account folder for things like EBS or ECR default KMS Customer managed keys.
I create an environments folder for each different independent.