Skip to content

v0.12.2 Refactoring and enabling work#1310

Open
citkane wants to merge 19 commits into
webview:masterfrom
citkane:Refactor-and-enabling-work
Open

v0.12.2 Refactoring and enabling work#1310
citkane wants to merge 19 commits into
webview:masterfrom
citkane:Refactor-and-enabling-work

Conversation

@citkane
Copy link
Copy Markdown
Contributor

@citkane citkane commented Jun 18, 2025

This is primarily a housekeeping release aimed at code readability, maintainability and enabling work for upcoming enhancements.

It has a large diff footprint, but does not change existing functionality ensuring 100% backwards compatibility.

Changed

  • The 'core/include/webview' folder structure is flattened to 'core/include'.
  • The file folder structure and namespaces have been coordinated to reflect code purpose and encapsulation.
  • Namespace tails are followed by API structs and classes with improved inline documentation about the purpose of each internal API.
  • Much of the code definitions and implementations have been separated with improved inline documentation in header files.
  • Some existing code has been refactored for improved encapsulation and readability.
  • All JS/HTML string generation has been moved to a tokenised template system with a string retrieval API.

Fixed

  • Unlike Linux and Windows, the Darwin backend does not accept navigate URL strings with leading or trailing whitespace, causing silent execution anomalies. URL strings are now automatically trimmed for Darwin.

Deprecated

  • The webview::webview C++ API class naming is ambiguous for compilers and humans, so webview_cc is now declared in the Global namespace and should be used instead.
  • #include "webview/webview.h" is deprecated in favour of #include "webview.h".

Depends on PR's

@citkane
Copy link
Copy Markdown
Contributor Author

citkane commented Jun 19, 2025

@StefanL, this is again a preparatory PR like #1316. There are however some deprecation and code structure changes which I will motivate below:

Separation of header definition files and functional implementation files is essential for forward declarations and negating recursive inclusion issues.

Even without recursive inclusions, NOT separating the files becomes wieldy (especially with docstrings), and for many people like me, incredibly cumbersome to read. The header file should at it's best be easily understood at a glance and give an unfamiliar developer an overview of the purpose and structure of a class / struct / function, etc.

The namespace and file structure hierarchy benefits by matching as closely as reasonable, thus helping unfamiliar developers understand the purpose of each domain at a glance, and find things easily.

Individual API's under a namespace domain benefit by being a class or struct for two reasons which I will illustrate by example:

  1. I can do: using namespace webview::strings, which contains the static string API struct, and now in my code when I type string:: I get presented the root of the hierarchical API tree via autocomplete.
  2. When somebody reads the code, they see string::err.some_value() which is clear about the domain context of string::, thus making naming things much simpler. Multiple domains can contextually re-use names, and we avoid very_long_names_for_things_because_ambiguity_causes_confusion, along with long flat IDE lists that are challenging.

I have flattened the "core/include/webview" folder root to "core/include".
"core/include/webview/webview.h" (now deprecated) still exists, and does #include "../webview.h". This inverts the current situation, retains backward compatibility and eliminates the unnecessary folder nesting.

webview::webview is ambiguous. Depending on the scope within the same implementation file, it must be used either as webview::webview or webview. This is not just problematic for humans. MSVC compiler agrees, and it alone errors in certain situations pointing out this ambiguity. I have deprected webview::webview (which will still work, so backward compatibility is fine) and provided webview_cc in the Global namespace instead. This is much clearer.

I have changed all #include ""'s to be absolute from the root include. This is safer, convenient if a file where ever to change location and provides an unfamiliar developer the domain context of the include at a glance.

With the exception of <windows.h>, which should be included before all others, I have grouped include statements and relevant macro statements in a consistent pattern and minimalised line break usage. Line-breaks imply a change in purpose, which unnecessarily stops ones eye at the top of a file for no good reason.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant