Resolve "Change the processing of the `stories` rule to a `height` GEM Taxonomy tag"

Closes #15 (closed)

building/02_process/height_and_floorspace/height_and_floorspace.py

@@ -36,29 +36,25 @@ class HeightAndFloorspaceRule:
 
         gem_taxonomy_height = []
 
-        # The number of stories ideally comes from the tags from OpenStreetMap. If we are able
-        # to use that, we can also calculate the floorspace. The height tags in
-        # OSM are also parsed, but no floorspace is estimated.
+        # The number of stories ideally comes from the `building:levels` tags in OpenStreetMap. If they are present,
+        # the floorspace of a building can be calculated. OpenStreetMap buildings can also contain a `height` tag but
+        # this tag is only parsed without the floorspace being estimated.
         try:
             stories, floorspace = self.get_stories_and_floorspace_from_osm(tags, area)
-        # OSM can have unexpected data types in their tagging scheme, therefore we do not raise
+        # OSM can have unexpected data types and unexpected content in their tagging scheme, therefore we do not raise
         # an exception in case of a ValueError, but instead ignore the values.
         except ValueError:
             stories, floorspace = None, None
         if stories:
             gem_taxonomy_height.append(stories)
 
-        # TODO: add the height attribute from OSM
-
-        # If any of the number of stories and height are found in OSM, these are returned.
+        # If any of the number-of-stories and height tags are found in OpenStreetMap, they are returned.
         if len(gem_taxonomy_height) > 0:
             return {
                 "height": "+".join(gem_taxonomy_height),
                 "floorspace": floorspace,
             }
 
-        # TODO: add the stories attribute from GHSL
-
         return {"height": None, "floorspace": None}
 
     def get_stories_and_floorspace_from_osm(self, tags: dict, area: float):
@@ -86,7 +82,7 @@ class HeightAndFloorspaceRule:
         underground_stories = self.tag_to_float(tags, "building:levels:underground")
         min_stories = self.tag_to_float(tags, "building:min_level")
 
-        # Parse the main stories and roof stories.
+        # Parse the number of main stories and roof stories.
         stories = 0
         floorspace = 0
         if main_stories or roof_stories:
@@ -95,13 +91,13 @@ class HeightAndFloorspaceRule:
                 floorspace += main_stories * area
             if roof_stories:
                 stories += roof_stories
-                # Take only 50% of the floorspace for roof stories
+                # Take only 50% of the floorspace for roof stories.
                 floorspace += roof_stories * area * 0.5
             if min_stories:
                 stories -= min_stories
                 floorspace -= min_stories * area
 
-            # Ceil the number of stories
+            # Ceil the number of stories.
             stories = ceil(stories)
 
         # Parse the underground story tag.
@@ -111,7 +107,7 @@ class HeightAndFloorspaceRule:
         else:
             underground_stories = 0
 
-        # Take a factor of 90% for the floorspace
+        # Take a factor of 90% for the floorspace.
         floorspace *= 0.9
 
         # Check if anything is wrong with the tags.
@@ -122,7 +118,7 @@ class HeightAndFloorspaceRule:
         elif stories + underground_stories > 175:
             return None, None
 
-        # Create the story tag according to the GEM taxonomy.
+        # Create the number-of-stories tag of the height attribute.
         story_tags = []
         if stories != 0:
             story_tags.append(f"H:{stories}")
@@ -153,7 +149,7 @@ class HeightAndFloorspaceRule:
         if tag_value is None or tag_value == "":
             return None
 
-        # If the tag does exist, try to convert it to float. If that resolves in a value error,
+        # If the tag does exist, try to convert it to float. If that raises a `ValueError`,
         # return None.
         try:
             return float(tag_value)