MVC Naming Convention Guide

Consistent naming for Views, Controllers, Models, and related classes.

---

Class Naming

Views (full-page/screen)

A View is a full page or screen that lives in a QStackedWidget. It represents a top-level UI section the user navigates to.

Convention	Example
{Name}View	HomeView, SoftwareView, StartupView, SettingsView

File: {name}_view.py

# home_view.py
class HomeView(QWidget):
    """Full-page view for the home screen."""
    ...

Do NOT use: HomeWidgetView, HomeViewWidget, HomePanelView

---

Widgets (reusable components)

A Widget is a smaller, reusable UI component that is embedded inside a View or another Widget. Cards, list items, toolbars, and custom controls all fall into this category.

Convention	Example
{Name}Widget	ProjectCardWidget, IssueItemWidget, LoadingSpinnerWidget

File: {name}_widget.py

# project_card_widget.py
class ProjectCardWidget(QWidget):
    """Card widget displaying a single project summary."""
    ...

Note: If the component clearly extends a specific Qt base, prefer the Qt suffix where it adds clarity (e.g., MilestoneCalendarWidget for a QCalendarWidget subclass).

---

Dialogs (popups/modals)

A Dialog is a popup window (modal or modeless) that appears above the main UI.

Convention	Example
{Name}Dialog	SignProjectDialog, ExportDialog, ConfirmationDialog

File: {name}_dialog.py

# sign_project_dialog.py
class SignProjectDialog(QDialog):
    """Dialog for signing a project with user credentials."""
    ...

Do NOT use: SignPrjDialogView, ExportDialogWidget

---

Controllers

A Controller coordinates a View and its business logic. One controller per system/feature.

Convention	Example
{Name}Controller	HomeController, SoftwareController, StartupController

File: {name}_controller.py

# home_controller.py
class HomeController(QObject):
    """Controller for the home system."""
    ...

Do NOT use: HomeWindowController, HomeViewPresenter

Exception: The application-level orchestrator uses MainController (not MainWindowController).

---

Models

A Model holds data and business logic, independent of the UI.

Convention	Example
{Name}Model	ProjectTreeModel, IssueListModel
{Name}Item	ProjectItem, LibraryItem (for data objects in tree/list models)

File: {name}_model.py or {name}_item.py

---

View Index Enums

View index enums map readable names to QStackedWidget page indices. They live in constants/view_indices.py.

Convention	Example
{Name}Page	SoftwarePage, MainPage, StartupPage

File: view_indices.py

# view_indices.py
from enum import IntEnum

class SoftwarePage(IntEnum):
    """Page indices for the software stacked widget."""
    DEV_TOOLS = 0
    SOFTWARE_TOOLS = 1
    PLANT_DESIGN = 2
    HOME = 3

Rationale: Using Page for the enum avoids collision with the View class of the same system (e.g., SoftwareView the class vs. SoftwarePage the enum).

---

File Naming

All Python files use snake_case. The file name should match the primary class it contains.

Class	File
HomeView	home_view.py
HomeController	home_controller.py
ProjectCardWidget	project_card_widget.py
SignProjectDialog	sign_project_dialog.py

Do NOT use: camelCase (projectClass.py), abbreviations (pd_prop_diag_edit_view.py when property_dialog_edit_view.py is clearer), or redundant prefixes when the folder already provides context.

---

Summary Table

Type	Suffix	Example Class	Example File
Full-page view	View	StartupView	startup_view.py
Reusable component	Widget	ProjectCardWidget	project_card_widget.py
Dialog/popup	Dialog	ExportDialog	export_dialog.py
Controller	Controller	StartupController	startup_controller.py
Data model	Model	ProjectTreeModel	project_tree_model.py
Data item	Item	ProjectItem	project_item.py
Page index enum	Page	SoftwarePage	view_indices.py

---

Anti-Patterns

These naming patterns should NOT be used:

Bad	Good	Why
HomeWidgetView	HomeView	"Widget" is redundant, it is already a QWidget
HomeWindowController	HomeController	"Window" is misleading, controllers manage views not windows
LoggingViewWidget	LogSettingsView	Pick either View or Widget, not both
SignPrjDialogView	SignProjectDialog	Don't combine Dialog and View, and avoid abbreviations
SoftwareView (IntEnum)	SoftwarePage	Enums use Page to avoid collision with the View class