added comments and refactored code

lib/pages/landing_page.dart

@@ -17,7 +17,7 @@ class LandingPage extends StatefulWidget {
 
 // uses mixin OverlayService to show loading overlay
 class _LandingPageState extends State<LandingPage> with OverlayService {
-  late FloodStationProvider floodStationProvider;
+  late FloodStationProvider _floodStationProvider;
 
   @override
   void dispose() {
@@ -27,7 +27,7 @@ class _LandingPageState extends State<LandingPage> with OverlayService {
 
   @override
   Widget build(BuildContext context) {
-    floodStationProvider = context.watch<FloodStationProvider>();
+    _floodStationProvider = context.watch<FloodStationProvider>();
     return Column(
       children: [
         StationFilter(
@@ -54,9 +54,9 @@ class _LandingPageState extends State<LandingPage> with OverlayService {
 
     return Expanded(
       child: FloodStationListView(
-        stations: floodStationProvider.filtered
-            ? floodStationProvider.filteredStations
-            : floodStationProvider.allStations,
+        stations: _floodStationProvider.filtered
+            ? _floodStationProvider.filteredStations
+            : _floodStationProvider.allStations,
         onItemTapped: _navigateToStationDetail,
       ),
     );
@@ -64,7 +64,7 @@ class _LandingPageState extends State<LandingPage> with OverlayService {
 
   void _handleFilterChange(String filterText) {
     if (filterText.isEmpty) {
-      floodStationProvider.filtered = false;
+      _floodStationProvider.filtered = false;
       setState(() {});
       return;
     }
@@ -73,14 +73,14 @@ class _LandingPageState extends State<LandingPage> with OverlayService {
       context: context,
       message: 'Loading',
       onDismiss: () {
-        floodStationProvider.cancelFilterLoading();
+        _floodStationProvider.cancelFilterLoading();
       },
     );
 
-    floodStationProvider.loadFilteredStations(filterText);
-    floodStationProvider.filteredStationsFuture
+    _floodStationProvider.loadFilteredStations(filterText);
+    _floodStationProvider.filteredStationsFuture
         ?.then((_) => removeLoadingNotifier());
-    floodStationProvider.filtered = true;
+    _floodStationProvider.filtered = true;
   }
 
   void _handleLoadAllStations() {
@@ -88,27 +88,27 @@ class _LandingPageState extends State<LandingPage> with OverlayService {
       context: context,
       message: 'Loading',
       onDismiss: () {
-        floodStationProvider.cancelFilterLoading();
+        _floodStationProvider.cancelFilterLoading();
       },
     );
 
-    floodStationProvider
+    _floodStationProvider
         .loadAllStations()
         .whenComplete(() => removeLoadingNotifier());
   }
 
   void _navigateToStationDetail(FloodStation station) {
-    floodStationProvider.selectedStation = station;
+    _floodStationProvider.selectedStation = station;
     Navigator.of(context).pushNamed(FloodStationPage.routeName);
   }
 
   // returns boolean to decide whether the list of stations should be shown
   // if the list of stations is empty and is not filtered either, the function returns false
   bool get _shouldShowList {
-    if (!floodStationProvider.filtered &&
-        floodStationProvider.allStations.isNotEmpty) {
+    if (!_floodStationProvider.filtered &&
+        _floodStationProvider.allStations.isNotEmpty) {
       return true;
     }
-    return floodStationProvider.filtered;
+    return _floodStationProvider.filtered;
   }
 }

lib/pages/main_navigation_scaffold.dart

@@ -5,6 +5,7 @@ import 'map_page.dart';
 
 class MainNavigationScaffold extends StatefulWidget {
   const MainNavigationScaffold({super.key});
+
   static const routeName = '/';
 
   @override
@@ -12,13 +13,13 @@ class MainNavigationScaffold extends StatefulWidget {
 }
 
 class _MainNavigationScaffoldState extends State<MainNavigationScaffold> {
-  int _selectedPageIndex = 0;
-
   final List<Widget> _pages = [
     const LandingPage(),
     const MapPage(),
   ];
 
+  int _selectedPageIndex = 0;
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
@@ -32,6 +33,7 @@ class _MainNavigationScaffoldState extends State<MainNavigationScaffold> {
           NavigationDestination(icon: Icon(Icons.map_outlined), label: 'Map'),
         ],
       ),
+      // Used IndexedStack to save the page state while navigating
       body: IndexedStack(
         index: _selectedPageIndex,
         children: _pages,

lib/pages/map_page.dart

@@ -20,7 +20,7 @@ class MapPage extends StatefulWidget {
 }
 
 class _MapPageState extends State<MapPage> {
-  final mapController = MapController();
+  final _mapController = MapController();
   late FloodStationProvider _floodStationProvider;
 
   @override
@@ -35,7 +35,7 @@ class _MapPageState extends State<MapPage> {
       );
     }
     return FlutterMap(
-      mapController: mapController,
+      mapController: _mapController,
       options: MapOptions(
         cameraConstraint: CameraConstraint.containCenter(
             bounds: LatLngBounds.fromPoints(_floodStationProvider.allStations
@@ -47,7 +47,7 @@ class _MapPageState extends State<MapPage> {
         initialZoom: 6,
       ),
       children: [
-        openStreetMapTileLayer,
+        _openStreetMapTileLayer,
         MarkerClusterLayerWidget(
           options: MarkerClusterLayerOptions(
               maxClusterRadius: 45,
@@ -56,13 +56,14 @@ class _MapPageState extends State<MapPage> {
               padding: EdgeInsets.all(50),
               maxZoom: 15,
               markers: _stationsAsMarkers(_floodStationProvider.allStations),
-              builder: _markerBuilder),
+              builder: _clusterMarkerBuilder),
         )
       ],
     );
   }
 
-  Widget _markerBuilder(BuildContext context, List<Marker> markers) {
+  // builds the clustered marker
+  Widget _clusterMarkerBuilder(BuildContext context, List<Marker> markers) {
     return Container(
       decoration: BoxDecoration(
         borderRadius: BorderRadius.circular(20),
@@ -71,12 +72,13 @@ class _MapPageState extends State<MapPage> {
       child: Center(
         child: Text(
           markers.length.toString(),
-          style: const TextStyle(color: Colors.white),
+          style: TextStyle(color: Theme.of(context).colorScheme.onTertiary),
         ),
       ),
     );
   }
 
+  // gets a list of markers from the list of all stations
   List<Marker> _stationsAsMarkers(List<FloodStation> stations) {
     return stations
         .map<Marker>(
@@ -91,7 +93,7 @@ class _MapPageState extends State<MapPage> {
         .toList();
   }
 
-  _markerTapped(FloodStation station) {
+  void _markerTapped(FloodStation station) {
     showDialog(
       context: context,
       builder: (context) => MapPopup(
@@ -104,7 +106,7 @@ class _MapPageState extends State<MapPage> {
   }
 }
 
-TileLayer get openStreetMapTileLayer => TileLayer(
+TileLayer get _openStreetMapTileLayer => TileLayer(
       urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
       userAgentPackageName: 'dev.fleaflet.flutter_map.example',
       tileProvider: CancellableNetworkTileProvider(),