https://platformengineering.org logo
Title
k

Kacper Twardowski

11/29/2022, 4:08 PM
Do you have some framework, or some practises in documenting code in terraform? Like that code is more clean, clear, and understanble for others, also in case you need to onboard new person.
t

Thomas Harris

11/30/2022, 10:16 AM
the beauty of HCL + Terraform is that it is, in general, self-documenting 🙂 I like to call it "executable documentation" for my infrastructure. If you are doing non best practice things such as using local/remote execs, then it is good practice to call out the reason for using these in a comment. There is also this tool, which is pretty useful: https://terraform-docs.io/
for creating code that is clean and less brittle, don't forget DRY (Don't Repeat Yourself)
a

Alex T.

11/30/2022, 6:15 PM
Yeah, I’d subscribe with the use of terraform-docs. However, I’ve seen that usually proper
descriptions
attributes are either ignored, or just overlooked. When those attributes (either for input variables, but also, for output values) are properly described, enriched with enough information and guidance looking for clear “interfaces” and an easy understanding (E.g.: declaring explicitly what’s required, values allowed, validations that are applied, links to references for official docs, or to the Terraform registry docs that belongs to the specific resource being created, etc.), the automation/generation of the docs is the easy part 😉 And, as @Thomas Harris mentioned — clear code in a way that resource blocks are concisely named, also helps!
s

Soren Martius

12/01/2022, 4:52 PM
take a look at Terramate 🙂 https://github.com/mineiros-io/terramate