|
| 1 | +--- |
| 2 | +# These are optional elements. Feel free to remove any of them. |
| 3 | +status: proposed |
| 4 | +contact: rogerbarreto |
| 5 | +date: 2025-02-11 |
| 6 | +deciders: markwallace, sergey, dmytro, weslie, evan, shawn |
| 7 | +--- |
| 8 | + |
| 9 | +# Structured Concepts |
| 10 | + |
| 11 | +## Context and Problem Statement |
| 12 | + |
| 13 | +Currently, the Concepts project has grown considerably, with many samples that do not consistently follow a structured pattern or guideline. |
| 14 | + |
| 15 | +A revisit of our sample patterns in favor of key drivers needs to be considered. |
| 16 | + |
| 17 | +This ADR starts by suggesting rules we might follow to keep new concepts following good patterns that make them easy to comprehend, find, and descriptive. |
| 18 | + |
| 19 | +The Semantic Kernel audience can vary greatly—from pro-devs, beginners, and non-developers. We understand that making sure examples and guidelines are as straightforward as possible is of our highest priority. |
| 20 | + |
| 21 | +### Decision Drivers |
| 22 | + |
| 23 | +- Easy to find |
| 24 | +- Easy to understand |
| 25 | +- Easy to set up |
| 26 | +- Easy to execute |
| 27 | + |
| 28 | +The above drivers focus on ensuring that we follow good practices, patterns, and a structure for our samples, guaranteeing proper documentation, simplification of code for easier understanding, as well as the usage of descriptive classes, methods, and variables. |
| 29 | + |
| 30 | +We also understand how important it is to ensure our samples are copy-and-paste friendly (work "as is"), being as frictionless as possible. |
| 31 | + |
| 32 | +## Solution |
| 33 | + |
| 34 | +Applying a set of easy-to-follow guidelines and good practices to the Concepts project will help maintain a good collection of samples that are easy to find, understand, set up, and execute. |
| 35 | + |
| 36 | +This guideline will be applied for any maintenance or newly added samples to the Concepts project. The contents may be added to a new CONTRIBUTING.md file in the Concepts project. |
| 37 | + |
| 38 | +> [!NOTE] |
| 39 | +> Rules/Conventions that are already ensured by analyzers are not mentioned in the list below. |
| 40 | +
|
| 41 | +## Rules |
| 42 | + |
| 43 | +### Sample Classes |
| 44 | + |
| 45 | +Each class in the Concepts project MUST have an xmldoc description of what is being sampled, with clear information on what is being sampled. |
| 46 | + |
| 47 | +✅ DO have xmldoc description detailing what is being sampled. |
| 48 | + |
| 49 | +✅ DO have xmldoc remarks for the required packages. |
| 50 | + |
| 51 | +✅ CONSIDER using xmldoc remarks for additional information. |
| 52 | + |
| 53 | +❌ AVOID using generic descriptions. |
| 54 | + |
| 55 | +✅ DO name classes with at least two words, separated by an underscore `First_Second_Third_Fourth`. |
| 56 | + |
| 57 | +✅ DO name classes with the `First` word reserved for the given concept or provider name (e.g., `OpenAI_ChatCompletion`). |
| 58 | + |
| 59 | +When the file has examples for a specific `<provider>`, it should start with the `<provider>` as the first word. `<provider>` here can also include runtime, platform, protocol, or service names. |
| 60 | + |
| 61 | +✅ CONSIDER naming `Second` and later words to create the best grouping for examples, |
| 62 | +e.g., `AzureAISearch_VectorStore_ConsumeFromMemoryStore`. |
| 63 | + |
| 64 | +✅ CONSIDER naming when there are more than two words, using a left-to-right grouping, |
| 65 | +e.g., `AzureAISearch_VectorStore_ConsumeFromMemoryStore`: for `AzureAISearch` within `VectorStore` grouping, there's a `ConsumeFromMemoryStore` example. |
| 66 | + |
| 67 | +### Sample Methods |
| 68 | + |
| 69 | +✅ DO have an xmldoc description detailing what is being sampled when the class has more than one sample method. |
| 70 | + |
| 71 | +✅ DO have descriptive method names limited to five words, separated by an underscore, |
| 72 | +e.g., `[Fact] public Task First_Second_Third_Fourth_Fifth()`. |
| 73 | + |
| 74 | +❌ DO NOT use `Async` suffix for Tasks. |
| 75 | + |
| 76 | +❌ AVOID using parameters in the method signature. |
| 77 | + |
| 78 | +❌ DO NOT have more than 3 samples in a single class. Split the samples into multiple classes when needed. |
| 79 | + |
| 80 | +### Code |
| 81 | + |
| 82 | +✅ DO keep code clear and concise. For the most part, variable names and APIs should be self-explanatory. |
| 83 | + |
| 84 | +✅ CONSIDER commenting the code for large sample methods. |
| 85 | + |
| 86 | +❌ DO NOT use acronyms or short names for variables, methods, or classes. |
| 87 | + |
| 88 | +❌ AVOID any references to common helper classes or methods that are not part of the sample file, |
| 89 | +e.g., avoid methods like `BaseTest.OutputLastMessage`. |
| 90 | + |
| 91 | +## Decision Outcome |
| 92 | + |
| 93 | +TBD |
0 commit comments