Repository navigation
2. Modeling Guidelines
The following guidelines describe recommended practices for writing ORBIT models. They are intended to improve readability, maintainability, collaboration, and AI-assisted generation.
Focus on describing the model itself rather than its visual representation.
Define structures, relationships, processes, and dependencies instead of attempting to control positioning or layout.
Prefer readability over brevity.
A model should be easy to understand without requiring interpretation, assumptions, or knowledge of project-specific conventions.
Names should clearly reflect the concepts they represent.
Choose descriptive identifiers that communicate intent and domain meaning.
State important information directly.
Avoid hiding meaning behind abbreviations, shortcuts, or implicit assumptions when a clear declaration is possible.
Elements that belong to the same logical context should be located close to one another.
Grouping related definitions improves readability and helps both humans and tools understand the model structure.
Use a single naming convention throughout a model or project.
Consistent terminology reduces confusion and makes large models easier to navigate.
Each model should have a clear purpose.
Avoid combining unrelated concerns into a single document when separate models would provide better clarity.
Avoid unnecessary comments, duplication, and excessive formatting.
The model should remain concise while preserving readability.
Models are often read more frequently than they are written.
Write definitions that remain understandable to future contributors and AI systems without additional context.
The same concepts should be represented consistently across related models.
Shared terminology and conventions help maintain coherence throughout a project.
Следующие рекомендации описывают предпочтительный стиль написания моделей ORBIT. Их цель — повысить читаемость, поддерживаемость, удобство совместной работы и качество генерации моделей с помощью ИИ.
Сосредоточьтесь на описании самой модели, а не её визуального представления.
Определяйте структуры, связи, процессы и зависимости вместо попыток управлять расположением элементов или компоновкой.
Отдавайте предпочтение читаемости, а не краткости или оригинальности записи.
Модель должна быть понятна без дополнительных интерпретаций, предположений или знания внутренних соглашений проекта.
Имена должны ясно отражать сущности, которые они обозначают.
Выбирайте понятные идентификаторы, передающие смысл и контекст предметной области.
Важная информация должна задаваться напрямую.
Не скрывайте смысл за сокращениями, неочевидными конструкциями или неявными предположениями, если существует более понятный способ описания.
Элементы, относящиеся к одному логическому контексту, должны находиться рядом друг с другом.
Группировка связанных определений улучшает читаемость и помогает людям и инструментам лучше понимать структуру модели.
Используйте единый подход к именованию внутри модели и проекта.
Последовательная терминология снижает вероятность ошибок и упрощает навигацию по большим моделям.
Каждая модель должна иметь чёткое назначение.
Не объединяйте в одном документе несвязанные задачи, если их можно описать отдельными моделями более понятно и аккуратно.
Не используйте лишние комментарии, дублирование информации и чрезмерное форматирование.
Модель должна оставаться компактной, сохраняя при этом хорошую читаемость.
Модели обычно читают гораздо чаще, чем создают.
Пишите определения так, чтобы они оставались понятными для будущих участников проекта и систем искусственного интеллекта без необходимости изучать дополнительный контекст.
Одни и те же понятия должны описываться одинаковым образом во всех связанных моделях.
Единая терминология и соглашения помогают поддерживать целостность проекта по мере его развития.