Define and enforce code conventions

[droguljic]

In current state there are no clearly defined code conventions which in the end translates into inconsistencies which reduce readability, maintenance and extensibility while slowly creating tech debt.

Types of inconsistencies found currently to illustrate the scope of problem:

• The index.ts file is in some situations used as barrel file and in other for resource component implementation
• The ordering of the namespace declaration is in most files before the class that is merged with, in files where enum is part of the namespace declaration is after class in order to be properly merged with the class
• Naming of the modules is messy, in some cases name of the module includes underlaying service for example ecs-service, while in others it is general such as database
• Exported classes do not always have the same name as the file exporting them
• Not all modules inside the src/components path are actual component resources
• Tests are most of the time lacking full type definitions of infrastructure outputs

Resolving the above state problems will increase code readability, ease maintenance and make the codebase future-proof. On top of that, it will also make consumer API more structured and user-friendly as internal structure is translated in the exported API.

Below is a list of conventions that potentially could be enforced to resolve mentioned inconsistencies (provided list is not set in stone as is up for debate, its main purpose is as a starting point for the discussion):

• Use index.ts files strictly as barrel files
• Always declare namespace after the class it is merged with
• Exported class must always match the name of the file exporting it
• Provide full type definitions for the infrastructure outputs in tests
• Reorganize modules following way:
  • Split components into two folders, components and constructs, where components host only lower-order implementations such as ecsService, acmCertificate, etc. Use constructs to host higher-order implementations such webServer, staticSite
  • For implementation in the src/components path use more general naming, such as tls->AcmCertificate, compute->EcsService, access->Password, network->Vpc
  • For implementation in the src/constructs only use components from the src/components path, e.g. for staticSite use cdn->Cloudfront and storage->S3, or for webServer use compute->EcsService and network->ApplicationLoadBalancer.
  • Move all observability related stuff, e.g. otel, grafana, prometheus, into the dedicated src/observability path.
• Optionally consider switching from kebab-case file/folder naming to camelCase.