Convention over configuration. Configuration before hard-coded logic.
This principle determines where technical decisions belong. The framework should infer predictable behavior from established conventions, apply standard defaults when values are absent, use configuration for legitimate variations, and reserve code for stable framework mechanisms.
The objective is not to eliminate configuration or code. It is to place each decision at the correct architectural level while reducing ambiguity, repeated analysis, and unnecessary implementation cost.
Reducing the Cost of Coordination
In a software development team, speed does not depend solely on writing code faster. It depends largely on reducing the inherent complexity of communicating abstract ideas and minimizing the number of decisions that must be made repeatedly.
When every developer uses different naming patterns, metadata structures, defaults, or implementation strategies, the team must continually interpret individual decisions. Every module requires additional explanation, every code review revisits the same questions, and every new developer must learn several personal approaches instead of one coherent system.
Conventions eliminate much of this friction by creating a shared technical language.
A convention transforms a repeated decision into an established rule:
This category of problem is solved this way, and every implementation follows the same rule.
The default implementation should not require repeated justification. It has already been analyzed, accepted, documented, and incorporated into the framework.
A deviation, however, is not free. It requires the team to determine:
Why does the standard rule not apply?
Is the exception technically necessary?
Should the framework support it?
Can configuration express it safely?
Does it introduce inconsistent behavior?
How will it be tested and maintained?
Could the same exception appear elsewhere?
Every deviation requires analysis. Analysis consumes engineering time, and engineering time creates cost. It also adds review, documentation, testing, maintenance, and onboarding overhead.
For this reason, deviations must be deliberate rather than accidental. A developer should not depart from an established convention merely because another implementation appears locally convenient.
When the same deviation appears repeatedly, it is no longer an isolated exception. The team should evaluate whether the convention must be extended, corrected, or replaced.
Conventions therefore do more than improve consistency. They reduce the number of decisions the team must analyze and communicate repeatedly.
Conventions Are Architectural Contracts
In the ITS Framework, conventions are not cosmetic rules. They are architectural contracts between the framework and the data it receives.
Naming connects several layers of the system:
SQL Server
DataSet and DataTable
XML serialization
Metadata processing
Runtime component activation
WinForms UI generation
When names and structures remain predictable, information can move through these layers without requiring custom mappings at every boundary. The same identifier can retain the same meaning from the database result set to the generated user interface.
For example:
id -> primary identifier
name -> standard display name
descr -> description
action_id -> related action identifier
action -> related display value
usr -> user reference
ts -> timestamp
csys_* -> framework or system data
Once this vocabulary is established, developers and framework components can infer intent directly.
An _id suffix identifies a relationship. A csys_ prefix identifies framework data. Standard descriptors such as id, name, and descr retain the same meaning throughout the system.
The convention becomes shared knowledge expressed through structure rather than repeated explanations.
Conventions Define Executable Behavior
A convention does not only determine how something is named. It determines how the framework behaves when that pattern is encountered.
The code is written to expect known patterns. When the framework receives a recognized pattern, it applies the corresponding behavior automatically.
The execution model is:
Recognized pattern
-> Apply the established behavior automatically.
Recognized pattern with an explicit override
-> Apply the configured variation.
Unknown or exceptional pattern
-> Require analysis and an explicit decision.
This allows behavior to be fixed and predictable without hard-coding every individual case.
For example, any column whose name begins with csys_ is classified as a system column. In the ITS Framework, that classification drives automatic behavior:
csys_state
csys_style
csys_status
csys_flags
These columns can be hidden automatically from end-user grids and forms because the convention identifies them as framework data rather than ordinary business data.
The framework does not need repetitive metadata such as:
column=csys_state&visible=false&type=system
column=csys_style&visible=false&type=system
column=csys_status&visible=false&type=system
column=csys_flags&visible=false&type=system
The prefix already communicates the classification:
The column belongs to the framework.
The column is not ordinary business data.
Apply system behavior.
Hide it from the end user by default.
The name is therefore not merely descriptive. It activates behavior.
The same model applies to other conventions:
id
-> Treat as the primary identifier.
name
-> Treat as the standard display value.
descr
-> Treat as descriptive or extended text.
action_id
-> Treat as a relationship key.
csys_*
-> Treat as framework data and hide by default.
Missing metadata
-> Apply the standard behavior.
The csys_ convention is especially important because it demonstrates the difference between a general framework rule and fragile hard-coding.
This would be fragile hard-coding:
If the column is csys_state, hide it.
If the column is csys_style, hide it.
If the column is csys_status, hide it.
If the column is csys_flags, hide it.
A convention allows one general rule:
If the column name begins with csys_, apply system-column behavior.
The first implementation grows through unrelated exceptions. The second implementation remains stable because it responds to a documented architectural contract.
The framework can rely on the behavior because the team has agreed to produce the expected pattern. The convention constrains the input, and the engine applies a deterministic rule when that input is received.
The Team Must Follow the Same Rules
A convention provides value only when the team applies it consistently.
It cannot mean:
Use this pattern when convenient.
It must mean:
This is the standard pattern.
All implementations follow it.
Exceptions require explicit justification.
Individual preference is not sufficient reason to introduce a different naming structure or behavior. Local variations create global costs because every variation must later be understood by reviewers, maintainers, framework code, and future developers.
A deviation may be valid, but it must answer a real technical or business requirement. It should not result from personal style, incomplete knowledge of the framework, or an unwillingness to follow the established model.
A valid deviation should be:
Necessary
Explicit
Documented
Reviewed
Testable
Configurable when appropriate
Limited to a defined scope
A convention gives the team a known baseline. An exception creates a branch from that baseline. Every branch increases cognitive and maintenance cost.
The purpose is not to prevent engineering judgment. The purpose is to avoid spending engineering judgment on problems that have already been solved.
Convention Before Configuration
A common mistake in data-driven systems is moving too much responsibility into configuration.
Every table receives metadata. Every field receives a descriptor. Every behavior receives a flag. Every default is explicitly stored. Over time, configuration becomes difficult to read, validate, migrate, and maintain.
Configuration should not repeat information that the framework can already infer.
For example, metadata such as the following usually adds noise rather than meaning:
visible=true
enabled=true
readonly=false
cache=true
load=default
When these values represent standard behavior, their absence should mean:
Use the standard behavior.
Configuration should describe only an intentional variation:
load=delayed
This keeps metadata meaningful. A configuration value exists because something differs from the standard, not because every default must be restated.
The design preference is:
1. Infer intent from convention.
2. Apply a standard default when information is absent.
3. Require configuration only for intentional variation.
Runtime precedence must remain explicit:
Valid configuration override exists
-> Apply the configured behavior.
Configuration override is absent
-> Apply the convention or standard default.
Convention defines the normal behavior. Configuration changes that behavior only when necessary.
For example:
Column starts with csys_
-> Hide it by convention.
Column starts with csys_ and explicitly specifies visible=true
-> Show it because configuration overrides the default behavior.
This preserves both predictability and flexibility.
Missing metadata is not necessarily missing information. Its absence can itself be meaningful:
Key present
-> Intentional override.
Key absent
-> Use convention or default.
A mature framework should not require developers to configure what the framework already knows.
Configuration Before Hard-Coded Logic
Conventions cannot resolve every decision.
Some behaviors legitimately vary by module, client, deployment, workflow, dataset, or business process. These decisions should be expressed through configuration rather than embedded directly in source code.
Examples include:
Which module should open?
Which form should be loaded?
Which stored procedure should retrieve the data?
Which validation rule should apply?
Which command should be enabled?
Which relationship should be used?
Which control should edit a value?
Which report should be launched?
These are application-level decisions. Because they are expected to vary, they belong in configuration.
Embedding variable decisions directly in code creates an unnecessary change cycle:
Change the requirement
Modify the source code
Compile
Deploy
Test the framework
Retest the module
Configuration allows application behavior to change without modifying the framework engine. The engine remains stable while configuration expresses the variable intent of each module or workflow.
The distinction is:
Expected to remain stable
-> Framework code.
Expected to vary
-> Configuration.
Predictable from structure
-> Convention.
Absent but covered by standard behavior
-> Default.
Configuration should not duplicate conventions, but conventions should not be forced to represent behavior that is legitimately variable.
Stable Mechanisms Belong in Code
Stable framework mechanisms should remain in code.
Examples include:
Metadata parsing
Default resolution
Parameter resolution
Cache infrastructure
XML reconstruction
Naming normalization
Runtime activation
UI composition
Debounce mechanics
Convention enforcement
Configuration override resolution
These mechanisms define how the framework operates. They are reusable, testable, and consistent across applications.
The architectural boundary is straightforward:
Stable mechanisms belong in code. Variable application decisions do not.
The framework should not hard-code which business form opens, which client-specific validation applies, or which report a command launches.
It should implement the reliable mechanism that:
Reads configuration
Recognizes conventions
Resolves defaults
Validates metadata
Detects system fields
Creates UI components
Activates the appropriate module
Applies explicit overrides
For example, the rule that recognizes the csys_ prefix belongs in framework code because it is a stable mechanism used throughout the system.
The list of specific csys_ columns does not need to be hard-coded. The engine implements the general rule, and the convention determines which columns match it.
Conventions Must Be Explicit and Enforceable
A convention is useful only when it is predictable.
A healthy convention should be:
Unambiguous
Stable
Documented
Consistently applied
Automatically validated where possible
Overridable when a legitimate exception exists
Poorly designed conventions create hidden behavior. If developers cannot determine why the framework made a decision, the convention has become implicit magic rather than a useful contract.
The framework should make conventions visible through:
Clear naming standards
Centralized resolution logic
Validation messages
Diagnostic logging
Automated tests
Code review rules
Technical documentation
When a convention is violated, the framework should fail clearly or report the inconsistency whenever possible.
For example, if a system field does not use the csys_ prefix, the engine cannot safely infer that it must be hidden. The result may be an internal field displayed to the end user or additional configuration added only to compensate for inconsistent naming.
The convention and the code must therefore agree:
The team produces a recognized pattern.
The framework expects that pattern.
The framework applies the documented behavior.
This agreement is the architectural contract.
Exceptions Must Remain Exceptional
Not every variation should become a new convention.
A convention is justified when a pattern is repeated, stable, and broadly useful. A configuration override is justified when a legitimate variation applies only to a specific module, client, workflow, or dataset.
The team should evaluate repeated deviations using questions such as:
Is this exception appearing in multiple modules?
Does it represent a stable pattern?
Would a general rule simplify the framework?
Would changing the convention break existing behavior?
Can the variation remain explicit configuration?
Does the proposed convention communicate intent clearly?
The result should follow one of three paths:
Isolated legitimate variation
-> Keep it as configuration.
Repeated stable variation
-> Consider a new or revised convention.
Unnecessary variation
-> Remove it and follow the existing convention.
This prevents two opposite failures:
Too many conventions
-> Hidden complexity and excessive implicit behavior.
Too many exceptions
-> Repeated analysis, inconsistent code, and configuration noise.
The goal is not maximum convention. The goal is the correct balance between predictable standards and explicit variation.
The Decision Model
A practical decision model for ITS Framework is:
Can the framework infer the intent safely and unambiguously?
-> Use a convention.
Is the value absent but covered by standard expected behavior?
-> Use a default.
Does the behavior vary by module, client, dataset, or workflow?
-> Use configuration.
Is it a stable and reusable framework mechanism?
-> Implement it in code.
Does an implementation deviate from an established convention?
-> Require analysis and explicit justification.
Does the same deviation appear repeatedly?
-> Evaluate whether the convention should be revised.
Examples:
Table name is singular
-> Convention.
Column name is lowercase
-> Convention.
Column is named id, name, or descr
-> Convention.
Column ends with _id
-> Relationship convention.
Column begins with csys_
-> System-column convention.
csys_ column is hidden from the user
-> Automatic framework behavior.
Metadata key is absent
-> Standard default.
Metadata key is present
-> Explicit configuration override.
A module loads a specific report
-> Configuration.
Metadata parser implementation
-> Framework code.
A developer uses a different system prefix
-> Deviation requiring analysis.
This model separates architectural responsibilities and prevents local decisions from creating system-wide inconsistency.
How Conventions Save Time and Cost
Every technical decision has a cost.
Someone must:
Analyze it
Explain it
Implement it
Review it
Test it
Document it
Maintain it
Debug it
Teach it to other developers
If the same decision is made independently in every module, the organization pays that cost repeatedly.
A convention allows the team to analyze the problem once and reuse the resulting decision across the framework.
Instead of repeatedly asking:
Is this a primary key?
Is this a relationship?
Is this a system column?
Should this field be visible?
What does missing metadata mean?
Should this behavior be configured?
the framework and the team already know the answers.
This creates several compounding benefits:
Faster onboarding
Shorter code reviews
Fewer naming debates
Less metadata
Fewer custom mappings
Less special-case code
More predictable UI behavior
Safer framework automation
Lower maintenance cost
A convention reduces not only the amount of code but also the amount of communication required to understand that code.
The team spends less time resolving preventable ambiguity and more time implementing actual business requirements.
The Rule Can Be Summarized as Follows
At I.T.S., established conventions define how common problems are solved and how the framework responds to recognized patterns.
The team follows those conventions by default. A deviation requires analysis because it introduces additional technical, communication, testing, and maintenance cost.
The rule can be expressed as follows:
Follow established conventions by default.
Use the same pattern for the same problem.
Allow the framework to apply automatic behavior
when a recognized pattern is received.
Require analysis and explicit justification
for every deviation.
Remember that analysis consumes time,
and time creates cost.
Use configuration for legitimate variations.
Convert recurring exceptions into reviewed conventions
when a stable general rule can be established.
Keep stable framework mechanisms in code.
Or more concisely:
Do not configure what can be inferred.
Do not hard-code what can be configured.
Do not duplicate what can be standardized.
Do not deviate without analysis.
Do not repeat an exception that should become a rule.
Repeated structures become conventions. Missing values fall back to defaults. Variable intent becomes configuration. Stable infrastructure remains in code.
This gives ITS Framework three fundamental strengths:
Predictability from conventions
Flexibility from configuration
Stability from code
That is how ITS Framework reduces ambiguity, fixes expected behavior into reusable engine rules, improves technical communication, and converts consistency into development speed:
Convention over configuration. Configuration before hard-coded logic.