| 1 | <!-- markdownlint-disable MD022 MD032 --> |
| 2 | |
| 3 | # Engineering Reading Map v1 (.NET / C#) |
| 4 | |
| 5 | **Каноническая база знаний:** `kb-engineering-evidence-v1.md` — факты, эвристики и задачи внедрения по темам. Этот файл — справочник источников и опциональное углублённое чтение по трекам. |
| 6 | |
| 7 | ## Purpose |
| 8 | A practical literature map for resilient, confident, and effective .NET development. |
| 9 | |
| 10 | ## Version Baseline (Current) |
| 11 | - Language target: C# 14 and newer. |
| 12 | - Platform target: .NET 10 and newer. |
| 13 | - Compatibility rule: avoid unsupported combinations (for example, C# 14 on pre-.NET 10 targets). |
| 14 | - Build reliability rule: avoid `<LangVersion>latest</LangVersion>` for shared repos; prefer TFM-aligned defaults or explicit pinned versions (`14.0`, `15.0` when adopted). |
| 15 | |
| 16 | ## Evidence-Based Learning Protocol |
| 17 | - Fact: identify current gap (bug class, architecture weakness, delivery slowdown). |
| 18 | - Hypothesis: specify which source should reduce that gap and how. |
| 19 | - Check: apply one technique in a real task within 7 days. |
| 20 | - Decision criterion: keep only sources that measurably improve quality or speed. |
| 21 | - Confidence mark: tag adoption confidence (`low`, `medium`, `high`) after 2-3 uses. |
| 22 | |
| 23 | ## Track A: C# and .NET |
| 24 | - C# language docs (Microsoft Learn): modern language features and async model. |
| 25 | - What's new in C# 14 (Microsoft Learn): language delta map and migration implications. |
| 26 | - C# language versioning (Microsoft Learn): TFM-to-language compatibility and defaults. |
| 27 | - What's new in .NET 10 (Microsoft Learn): runtime/SDK/libraries release-level changes. |
| 28 | - C# in Depth (Jon Skeet): deep language semantics and tradeoffs. |
| 29 | - CLR via C# (Jeffrey Richter): runtime behavior, memory model, threading foundations. |
| 30 | - Pro .NET Memory Management (Konrad Kokosa): GC, allocations, performance diagnostics. |
| 31 | - .NET diagnostics docs (`dotnet-counters`, `dotnet-trace`, `dotnet-dump`): operational profiling workflow. |
| 32 | |
| 33 | ## Track B: Testing and Quality |
| 34 | - Unit testing best practices for .NET (Microsoft Learn): baseline conventions and anti-patterns. |
| 35 | - Integration testing in ASP.NET Core (Microsoft Learn): test host and realistic boundaries. |
| 36 | - xUnit official docs: framework idioms and maintainable test structure. |
| 37 | - xUnit Test Patterns (Gerard Meszaros): test smell taxonomy and refactoring. |
| 38 | - Unit Testing Principles, Practices, and Patterns (Vladimir Khorikov): test design economics. |
| 39 | - Working Effectively with Legacy Code (Michael Feathers): seam-based recovery in hard codebases. |
| 40 | - Test-Driven Development: By Example (Kent Beck): TDD micro-loop and feedback discipline. |
| 41 | |
| 42 | ## Track C: Design, Architecture, Refactoring |
| 43 | - Code Complete, 2nd ed. (Steve McConnell): practical software *construction* (routines, defensive programming, readability, reviews, testing, debugging, integration); chapter map and evidence protocol — `kb-mcconnell-code-complete-2-chapter-map-v1.md`; local copy path in that card. |
| 44 | - Refactoring (Martin Fowler): catalog and safe transformation strategy. |
| 45 | - Refactoring.Guru: quick pattern/smell lookup with C# examples. |
| 46 | - Clean Architecture (Robert C. Martin): dependency boundaries and policy layering. |
| 47 | - Domain-Driven Design (Eric Evans) + Implementing Domain-Driven Design (Vaughn Vernon): domain modeling and strategic design. |
| 48 | - Patterns of Enterprise Application Architecture (Martin Fowler): enterprise pattern language. |
| 49 | |
| 50 | ## Track D: Algorithms, Data Structures, Databases |
| 51 | - Introduction to Algorithms (CLRS): formal algorithmic toolkit. |
| 52 | - The Algorithm Design Manual (Steven Skiena): practical algorithm selection. |
| 53 | - Algorithms, 4th Edition (Sedgewick/Wayne): implementation-focused DS and algorithms. |
| 54 | - Designing Data-Intensive Applications (Martin Kleppmann): modern data system tradeoffs. |
| 55 | - Database Internals (Alex Petrov): storage engines, indexing, transaction internals. |
| 56 | - SQL Antipatterns (Bill Karwin): schema/query pitfalls and remediation patterns. |
| 57 | |
| 58 | ## Track E: Delivery and Engineering Methodology |
| 59 | - Accelerate (Forsgren/Humble/Kim): evidence-backed delivery metrics. |
| 60 | - Team Topologies (Skelton/Pais): socio-technical architecture for flow. |
| 61 | - The Pragmatic Programmer (Hunt/Thomas): robust engineering habits. |
| 62 | - Release It! (Michael Nygard): production stability and failure containment. |
| 63 | |
| 64 | ## Track F: Language Engineering and Compilers |
| 65 | - Compilers: Principles, Techniques, and Tools (Aho/Lam/Sethi/Ullman, Dragon Book): canonical compiler pipeline and optimization foundations. |
| 66 | - Dragon Book companion site (Stanford): errata, source appendix, course links for practical reinforcement. |
| 67 | - LLVM Kaleidoscope tutorial: modern IR-first implementation path from lexer/parser to JIT/object code. |
| 68 | - Crafting Interpreters (Nystrom): end-to-end interpreter/VM construction with emphasis on language ergonomics and runtime tradeoffs. |
| 69 | |
| 70 | ## Track G: F# and Mixed-Language .NET Architecture |
| 71 | - F# style guide and coding conventions (Microsoft Learn): maintainability principles for large codebases. |
| 72 | - F# component design guidelines (Microsoft Learn): API ergonomics and compatibility for C# consumers. |
| 73 | - Async vs task expressions (Microsoft Learn): choosing concurrency model by interoperability boundaries. |
| 74 | - Type providers (Microsoft Learn + FSharp.Data docs): schema-first integration with external data. |
| 75 | - .NET language strategy for F# (Microsoft Learn): long-term interoperability and ecosystem positioning. |
| 76 | |
| 77 | ## Track H: Windows/Linux Systems and Runtime Environments |
| 78 | - Operating System Concepts (Silberschatz/Galvin/Gagne): process, memory, scheduling, file systems, synchronization foundations. |
| 79 | - Modern Operating Systems (Tanenbaum/Bos): comparative OS architecture and tradeoff reasoning. |
| 80 | - The Linux Programming Interface (Kerrisk): Linux process/IPC/filesystem/networking behavior in production detail. |
| 81 | - Advanced Programming in the UNIX Environment (Stevens/Rago): Unix process model and systems interfaces. |
| 82 | - UNIX and Linux System Administration Handbook (Nemeth et al.): practical service/network/storage/ops patterns. |
| 83 | - Windows Internals (Russinovich et al.): Windows kernel/process/memory/I/O/security internals. |
| 84 | - Microsoft Learn (Windows + .NET diagnostics): service/runtime troubleshooting on Windows hosts. |
| 85 | - Linux man-pages/systemd/kernel docs: service control, limits, and low-level operational contracts. |
| 86 | |
| 87 | ### Track H: Application Examples (Requested) |
| 88 | - **Windows foundation example:** correlate a latency spike to thread-pool starvation using EventCounters + ETW/EventPipe trace, then validate with blocking-stack analysis. |
| 89 | - **Linux foundation example:** correlate service instability to cgroup limits (`memory.max`, CPU quota) + `systemd` restart policy, then validate via journald and `/proc` pressure signals. |
| 90 | |
| 91 | ## Execution Cadence |
| 92 | - Weekly rhythm: |
| 93 | - 1 deep source (book chapter or long guide), |
| 94 | - 1 operational source (docs/tutorial), |
| 95 | - 1 applied experiment in active code. |
| 96 | - Monthly output: |
| 97 | - 1 playbook delta, |
| 98 | - 1 anti-pattern note, |
| 99 | - 1 validated engineering checklist update. |
| 100 | |
| 101 | ## Ingestion Contract |
| 102 | - Every completed source gets a knowledge entry in `kb-engineering-evidence-v1.md` (по темам, не по батчам). |
| 103 | - Entry format: |
| 104 | - source and date, |
| 105 | - key facts, |
| 106 | - applicable heuristics, |
| 107 | - first practical adoption task, |
| 108 | - confidence mark after 2-3 usages. |
| 109 | - Batch size rule (fast mode): process 6-10 sources per pass before reporting status. |
| 110 | - Priority order: |
| 111 | 1. Official platform/runtime/testing docs (high volatility). |
| 112 | 2. Core engineering books (low volatility, high leverage). |
| 113 | 3. Supplemental references and pattern catalogs. |
| 114 | |
| 115 | ## Validation Metrics |
| 116 | - Fewer escaped defects in changed areas. |
| 117 | - Reduced lead time for similar tasks. |
| 118 | - Lower mean time to debug root cause. |
| 119 | - More stable p95/p99 for critical flows. |
| 120 | - Lower review churn (fewer repeated comments). |
| 121 | |
| 122 | ## Do Not Overfit |
| 123 | - Do not optimize for volume read. |
| 124 | - Prefer repeatable technique transfer over abstract coverage. |
| 125 | - Archive sources that do not survive real project constraints. |
| 126 | |
| 127 | <!-- markdownlint-enable MD022 MD032 --> |
| 128 | |
| 129 | |