← Барлық мақалаларға оралу

ADR-ды бюрократияға айналдырмай қалай қолдануға болады

Жарияланды

Architecture Decision Records (ADR) жүргізу - жақсы идея. Бірақ ADR guidelines-тың бәрін қатаң орындау тез арада бюрократиялық nightmare-ға айналуы мүмкін.

Documentation-пен жиі болатын жағдай сияқты, ол пайдалы tool емес, қосымша burden болып кетуі мүмкін. ADR-ды толтыруға және up to date ұстауға көп effort жұмсамай қалай жүргізуге болатынын қарастырайық.

ADR жүргізу бойынша ұсыныстар

  • Барлық records үшін бір файл қолданыңыз, егер project шағын немесе жаңа болса және records саны 10-нан аз болса.

  • Text аз, substance көп. Мысалы, PostgreSQL таңдасаңыз, неге таңдағаныңызды қысқаша жазыңыз. SQL Server немесе Oracle сияқты alternatives-тен неге бас тартқаныңызды түгел тізудің қажеті жоқ.

  • Readability format-тан маңыздырақ. Free-form style ішінде жазылған бірнеше sentence көбіне formal template үшін ғана толтырылған strict fields-тен пайдалырақ болады.

  • Relevance-ке фокус жасаңыз. Records relevance олардың көлемінен немесе белгілі бір format-ты қатаң сақтауынан маңыздырақ.

ADR ішінде шын мәнінде не болуы керек

  • Decision date. Records-ты chronological order ішінде сақтаңыз.

  • Title. Decision туралы қысқаша description беріңіз.

  • Employee name. Бірнеше жылдан кейін employee әлі company ішінде жұмыс істеуі мүмкін. Егер жұмыс істемесе де, name project және оның history туралы білетін colleagues табуды жеңілдетеді.

  • Decision description. Нақты не шешілгенін түсіндіріңіз.

  • Constraints. Decision obvious болмаса немесе specific limitations әсерінен қабылданса, оларды жазыңыз.

  • Қажет болса, нақты class-қа link. Мысалы, Redis-ті data caching үшін қолдануды шешсеңіз, RedisCacheProvider.cs class көрсетуге болады. Бұл redundant көрінуі мүмкін, бірақ ADR GitHub Copilot көре алатын context ішіне түседі және project architectural decisions түсінуіне көмектеседі.

  • Unique record ID. ID және title XML comments ішінде reference ретінде қолданылуы мүмкін, мысалы RedisCacheProvider.cs ішінде. Бұл Copilot-пен жұмысты да тиімдірек етеді.

Мысал

# ADR-002: Choosing Redis for Data Caching

## Date

2025-01-23

## Author

John Smith

## Decision Description

We have chosen **Redis** for data caching because it fully meets our requirements:

- High operation speed due to in-memory data storage.
- TTL support for managing data expiration.
- Reliability and fault tolerance proven by years of use in our department.
- Existing infrastructure for Redis is already deployed and configured in both testing and production environments.

The class `RedisCacheProvider.cs` will be used to implement caching in the project.

## Consequences

- Potential limitations in memory consumption for large data volumes.
- Minimal risks, as the team already has experience working with Redis.

Қорытынды

Егер project шағын болса немесе documentation үшін уақыт аз болса, ADR maintenance-ті жеңілдетіңіз, бірақ одан толық бас тартпаңыз. ADR records жаңа developers, GitHub Copilot және болашақта project-пен жұмыс істейтін employees үшін шынымен пайдалы болуы мүмкін.