Comment more unreferenced local labels (#550)

28 files changed, 133 insertions, 117 deletions

diff --git a/engine/battle/animations.asm b/engine/battle/animations.asm
index f66be640..eac4115a 100644
--- a/engine/battle/animations.asm
+++ b/engine/battle/animations.asm
@@ -22,7 +22,7 @@ DrawFrameBlock:
 	jp z, .flipHorizontalTranslateDown ; SUBANIMTYPE_HFLIP
 	dec a
 	jr z, .flipBaseCoords              ; SUBANIMTYPE_COORDFLIP
-.noTransformation
+; no transformation
 	ld a, [wBaseCoordY]
 	add [hl]
 	ld [de], a ; store Y
@@ -130,7 +130,7 @@ DrawFrameBlock:
 	ld a, [wNumFBTiles]
 	cp c
 	jp nz, .loop ; go back up if there are more tiles to draw
-.afterDrawingTiles
+; after drawing tiles
 	ld a, [wFBMode]
 	cp FRAMEBLOCKMODE_02
 	jr z, .advanceFrameBlockDestAddr ; skip delay and don't clean OAM buffer
@@ -185,7 +185,7 @@ PlayAnimation:
 	jr z, .AnimationOver
 	cp FIRST_SE_ID ; is this subanimation or a special effect?
 	jr c, .playSubanimation
-.doSpecialEffect
+; do Special Effect
 	ld c, a
 	ld de, SpecialEffectPointers
 .searchSpecialEffectTableLoop
@@ -295,11 +295,11 @@ LoadSubanimation:
 	and %11100000
 	cp SUBANIMTYPE_ENEMY << 5
 	vc_hook_blue Reduce_move_anim_flashing_Blizzard
-	jr nz, .isNotType5
-.isType5
+	jr nz, .isNotTypeEnemy
+; subanim type enemy
 	call GetSubanimationTransform2
 	jr .saveTransformation
-.isNotType5
+.isNotTypeEnemy
 	vc_hook Reduce_move_anim_flashing_Hyper_Beam
 	call GetSubanimationTransform1
 .saveTransformation
@@ -427,11 +427,11 @@ MoveAnimation:
 	call PlayAnimation
 	vc_hook_red Stop_reducing_move_anim_flashing_Bubblebeam_Mega_Kick
 	vc_hook_blue Stop_reducing_move_anim_flashing_Spore
-	jr .next4
+	jr .next
 .animationsDisabled
 	ld c, 30
 	call DelayFrames
-.next4
+.next
 	vc_hook_red Stop_reducing_move_anim_flashing
 	vc_hook_blue Stop_reducing_move_anim_flashing_Rock_Slide_Dream_Eater
 	call PlayApplyingAttackAnimation ; shake the screen or flash the pic in and out (to show damage)
@@ -1097,6 +1097,8 @@ SetAnimationBGPalette:
 	ldh [rBGP], a
 	ret
 
+AnimationUnusedShakeScreen: ; unreferenced
+; Shakes the screen for a while.
 	ld b, $5
 
 AnimationShakeScreenVertically:
diff --git a/engine/battle/core.asm b/engine/battle/core.asm
index 44fd9a70..dd9fbc71 100644
--- a/engine/battle/core.asm
+++ b/engine/battle/core.asm
@@ -1247,7 +1247,7 @@ SlideTrainerPicOffScreen:
 	ldh a, [hSlideAmount]
 	cp 8
 	jr z, .slideRight
-.slideLeft ; slide player sprite off screen
+; slide player sprite left off screen
 	ld a, [hld]
 	ld [hli], a
 	inc hl
@@ -3557,11 +3557,12 @@ CheckPlayerStatusConditions:
 	ld hl, AttackContinuesText
 	call PrintText
 	ld a, [wPlayerNumAttacksLeft]
-	dec a ; did multi-turn move end?
+	dec a
 	ld [wPlayerNumAttacksLeft], a
-	ld hl, GetPlayerAnimationType ; if it didn't, skip damage calculation (deal damage equal to last hit),
-	                ; DecrementPP and MoveHitTest
-	jp nz, .returnToHL
+	ld hl, GetPlayerAnimationType ; skip damage calculation (deal damage equal to last hit),
+	                              ; DecrementPP and MoveHitTest
+	jp nz, .returnToHL  ; redundant leftover code, the case wEnemyNumAttacksLeft == 0
+						; is handled within CheckNumAttacksLeft
 	jp .returnToHL
 
 .RageCheck
@@ -3626,7 +3627,7 @@ ConfusedNoMoreText:
 	text_far _ConfusedNoMoreText
 	text_end
 
-SavingEnergyText:
+SavingEnergyText: ; unreferenced
 	text_far _SavingEnergyText
 	text_end
 
@@ -4171,7 +4172,7 @@ GetDamageVarsForPlayerAttack:
 	ld a, [hl] ; a = [wPlayerMoveType]
 	cp SPECIAL ; types >= SPECIAL are all special
 	jr nc, .specialAttack
-.physicalAttack
+; physical attack
 	ld hl, wEnemyMonDefense
 	ld a, [hli]
 	ld b, a
@@ -4284,7 +4285,7 @@ GetDamageVarsForEnemyAttack:
 	ld a, [hl] ; a = [wEnemyMoveType]
 	cp SPECIAL ; types >= SPECIAL are all special
 	jr nc, .specialAttack
-.physicalAttack
+; physical attack
 	ld hl, wBattleMonDefense
 	ld a, [hli]
 	ld b, a
@@ -5301,7 +5302,6 @@ AdjustDamageForMoveType:
 	ld [hl], a
 	or b ; is damage 0?
 	jr nz, .skipTypeImmunity
-.typeImmunity
 ; if damage is 0, make the move miss
 ; this only occurs if a move that would do 2 or 3 damage is 0.25x effective against the target
 	inc a
@@ -5394,7 +5394,7 @@ MoveHitTest:
 	ldh a, [hWhoseTurn]
 	and a
 	jr nz, .enemyTurn
-.playerTurn
+; player's turn
 ; this checks if the move effect is disallowed by mist
 	ld a, [wPlayerMoveEffect]
 	cp ATTACK_DOWN1_EFFECT
@@ -5466,12 +5466,12 @@ MoveHitTest:
 	ld [wMoveMissed], a
 	ldh a, [hWhoseTurn]
 	and a
-	jr z, .playerTurn2
-.enemyTurn2
+	jr z, .playerTurn
+; enemy's turn
 	ld hl, wEnemyBattleStatus1
 	res USING_TRAPPING_MOVE, [hl] ; end multi-turn attack e.g. wrap
 	ret
-.playerTurn2
+.playerTurn
 	ld hl, wPlayerBattleStatus1
 	res USING_TRAPPING_MOVE, [hl] ; end multi-turn attack e.g. wrap
 	ret
@@ -6063,10 +6063,11 @@ CheckEnemyStatusConditions:
 	ld hl, AttackContinuesText
 	call PrintText
 	ld hl, wEnemyNumAttacksLeft
-	dec [hl] ; did multi-turn move end?
-	ld hl, GetEnemyAnimationType ; if it didn't, skip damage calculation (deal damage equal to last hit),
+	dec [hl]
+	ld hl, GetEnemyAnimationType ; skip damage calculation (deal damage equal to last hit),
 	                             ; DecrementPP and MoveHitTest
-	jp nz, .enemyReturnToHL
+	jp nz, .enemyReturnToHL ; redundant leftover code, the case wEnemyNumAttacksLeft == 0
+							; is handled within CheckNumAttacksLeft
 	jp .enemyReturnToHL
 .checkIfUsingRage
 	ld a, [wEnemyBattleStatus2]
@@ -6415,7 +6416,7 @@ QuarterSpeedDueToParalysis:
 	ldh a, [hWhoseTurn]
 	and a
 	jr z, .playerTurn
-.enemyTurn ; quarter the player's speed
+; enemy's turn, quarter the player's speed
 	ld a, [wBattleMonStatus]
 	and 1 << PAR
 	ret z ; return if player not paralysed
@@ -6458,7 +6459,7 @@ HalveAttackDueToBurn:
 	ldh a, [hWhoseTurn]
 	and a
 	jr z, .playerTurn
-.enemyTurn ; halve the player's attack
+; enemy's turn, halve the player's attack
 	ld a, [wBattleMonStatus]
 	and 1 << BRN
 	ret z ; return if player not burnt
@@ -6642,7 +6643,7 @@ LoadHudTilePatterns:
 	ldh a, [rLCDC]
 	add a ; is LCD disabled?
 	jr c, .lcdEnabled
-.lcdDisabled
+; LCD disabled
 	ld hl, BattleHudTiles1
 	ld de, vChars2 tile $6d
 	ld bc, BattleHudTiles1End - BattleHudTiles1
diff --git a/engine/battle/draw_hud_pokeball_gfx.asm b/engine/battle/draw_hud_pokeball_gfx.asm
index 768a6e20..adeaaf62 100644
--- a/engine/battle/draw_hud_pokeball_gfx.asm
+++ b/engine/battle/draw_hud_pokeball_gfx.asm
@@ -18,7 +18,7 @@ LoadPartyPokeballGfx:
 
 SetupOwnPartyPokeballs:
 	call PlacePlayerHUDTiles
-	ld hl, wPartyMon1
+	ld hl, wPartyMons
 	ld de, wPartyCount
 	call SetupPokeballs
 	ld a, $60
diff --git a/engine/battle/effects.asm b/engine/battle/effects.asm
index 2cef2521..22765140 100644
--- a/engine/battle/effects.asm
+++ b/engine/battle/effects.asm
@@ -230,7 +230,7 @@ FreezeBurnParalyzeEffect:
 	jr z, .burn1
 	cp FREEZE_SIDE_EFFECT1
 	jr z, .freeze1
-; .paralyze1
+; paralyze1
 	ld a, 1 << PAR
 	ld [wEnemyMonStatus], a
 	call QuarterSpeedDueToParalysis ; quarter speed of affected mon
@@ -283,7 +283,7 @@ FreezeBurnParalyzeEffect:
 	jr z, .burn2
 	cp FREEZE_SIDE_EFFECT1
 	jr z, .freeze2
-; .paralyze2
+; paralyze2
 	ld a, 1 << PAR
 	ld [wBattleMonStatus], a
 	call QuarterSpeedDueToParalysis
@@ -593,7 +593,7 @@ StatModifierDownEffect:
 	ld a, [de]
 	cp ATTACK_DOWN2_EFFECT - $16 ; $24
 	jr c, .ok
-	cp EVASION_DOWN2_EFFECT + $5 ; $44
+	cp ATTACK_DOWN_SIDE_EFFECT ; move side effects, stat mod decrease is always 1
 	jr nc, .ok
 	dec b ; stat down 2 effects only (dec mod again)
 	jr nz, .ok
@@ -711,7 +711,7 @@ CantLowerAnymore:
 
 MoveMissed:
 	ld a, [de]
-	cp $44
+	cp ATTACK_DOWN_SIDE_EFFECT
 	ret nc
 	jp ConditionalPrintButItFailed
 
@@ -1321,7 +1321,7 @@ DisableEffect:
 	cp LINK_STATE_BATTLING
 	pop hl ; wEnemyMonMoves
 	jr nz, .playerTurnNotLinkBattle
-; .playerTurnLinkBattle
+; player's turn, Link Battle
 	push hl
 	ld hl, wEnemyMonPP
 .enemyTurn
@@ -1456,6 +1456,7 @@ PlayCurrentMoveAnimation2:
 .notEnemyTurn
 	and a
 	ret z
+; fallthrough
 
 PlayBattleAnimation2:
 ; play animation ID at a and animation type 6 or 3
@@ -1482,6 +1483,7 @@ PlayCurrentMoveAnimation:
 .notEnemyTurn
 	and a
 	ret z
+; fallthrough
 
 PlayBattleAnimation:
 ; play animation ID at a and predefined animation type
diff --git a/engine/battle/ghost_marowak_anim.asm b/engine/battle/ghost_marowak_anim.asm
index 1040f85f..efda9f8f 100644
--- a/engine/battle/ghost_marowak_anim.asm
+++ b/engine/battle/ghost_marowak_anim.asm
@@ -48,7 +48,7 @@ MarowakAnim:
 	call Delay3
 	jp ClearSprites
 
-; copies a mon pic's  from background VRAM to sprite VRAM and sets up OAM
+; copies a mon pic's from background VRAM to sprite VRAM and sets up OAM
 CopyMonPicFromBGToSpriteVRAM:
 	ld de, vFrontPic
 	ld hl, vSprites
diff --git a/engine/battle/move_effects/substitute.asm b/engine/battle/move_effects/substitute.asm
index e4311209..01d5a8a3 100644
--- a/engine/battle/move_effects/substitute.asm
+++ b/engine/battle/move_effects/substitute.asm
@@ -37,8 +37,8 @@ SubstituteEffect_:
 	sbc 0
 	pop bc
 	jr c, .notEnoughHP ; underflow means user would be left with negative health
-                           ; bug: since it only branches on carry, it will possibly leave user with 0 HP
-.userHasZeroOrMoreHP
+                       ; bug: since it only branches on carry, it will possibly leave user with 0 HP
+; user has 0 or more HP
 	ld [hli], a ; save resulting HP after subtraction into current HP
 	ld [hl], d
 	ld h, b
diff --git a/engine/battle/move_effects/transform.asm b/engine/battle/move_effects/transform.asm
index 343fa3ca..95e17833 100644
--- a/engine/battle/move_effects/transform.asm
+++ b/engine/battle/move_effects/transform.asm
@@ -2,17 +2,22 @@ TransformEffect_:
 	ld hl, wBattleMonSpecies
 	ld de, wEnemyMonSpecies
 	ld bc, wEnemyBattleStatus3
+	; bug: on enemy's turn, a is overloaded with hWhoseTurn,
+	; before the check for INVULNERABLE
 	ld a, [wEnemyBattleStatus1]
 	ldh a, [hWhoseTurn]
 	and a
 	jr nz, .hitTest
+; player's turn
 	ld hl, wEnemyMonSpecies
 	ld de, wBattleMonSpecies
 	ld bc, wPlayerBattleStatus3
 	ld [wPlayerMoveListIndex], a
+	; bug: this should be target's BattleStatus1 (i.e. wEnemyBattleStatus1)
 	ld a, [wPlayerBattleStatus1]
 .hitTest
 	bit INVULNERABLE, a ; is mon invulnerable to typical attacks? (fly/dig)
+	                    ; this check doesn't work due to above bugs
 	jp nz, .failed
 	push hl
 	push de
diff --git a/engine/events/diploma.asm b/engine/events/diploma.asm
index 3d181210..e2a34a3b 100644
--- a/engine/events/diploma.asm
+++ b/engine/events/diploma.asm
@@ -73,8 +73,8 @@ DisplayDiploma::
 	jp GBPalNormal
 
 UnusedPlayerNameLengthFunc:
-; Unused function that does a calculation involving the length of the player's
-; name.
+; Unused function that performs bc = -(player name's length)
+; leftover from the JPN versions
 	ld hl, wPlayerName
 	lb bc, $ff, $00
 .loop
diff --git a/engine/events/pokemart.asm b/engine/events/pokemart.asm
index b280c711..cb25ab4c 100644
--- a/engine/events/pokemart.asm
+++ b/engine/events/pokemart.asm
@@ -99,7 +99,7 @@ DisplayPokemartDialogue_::
 	dec a
 	jr z, .sellMenuLoop
 
-.sellItem
+; sell item
 	ld a, [wBoughtOrSoldItemInMart]
 	and a
 	jr nz, .skipSettingFlag1
@@ -177,7 +177,7 @@ DisplayPokemartDialogue_::
 	dec a
 	jr z, .buyMenuLoop
 
-.buyItem
+; buy item
 	call .isThereEnoughMoney
 	jr c, .notEnoughMoney
 	ld hl, wNumBagItems
diff --git a/engine/events/prize_menu.asm b/engine/events/prize_menu.asm
index 15b991ed..1f71af42 100644
--- a/engine/events/prize_menu.asm
+++ b/engine/events/prize_menu.asm
@@ -195,7 +195,7 @@ HandlePrizeChoice:
 .getMonName
 	call GetMonName
 .givePrize
-	ld hl, SoYouWantPrizeTextPtr
+	ld hl, SoYouWantPrizeText
 	call PrintText
 	call YesNoChoice
 	ld a, [wCurrentMenuItem] ; yes/no answer (Y=0, N=1)
@@ -243,25 +243,25 @@ HandlePrizeChoice:
 	predef SubBCDPredef
 	jp PrintPrizePrice
 .bagFull
-	ld hl, PrizeRoomBagIsFullTextPtr
+	ld hl, PrizeRoomBagIsFullText
 	jp PrintText
 .notEnoughCoins
 	ld hl, SorryNeedMoreCoinsText
 	jp PrintText
 .printOhFineThen
-	ld hl, OhFineThenTextPtr
+	ld hl, OhFineThenText
 	jp PrintText
 
 UnknownPrizeData:
 ; XXX what's this?
 	db $00,$01,$00,$01,$00,$01,$00,$00,$01
 
-HereYouGoTextPtr:
+HereYouGoText: ; unreferenced
 	text_far _HereYouGoText
 	text_waitbutton
 	text_end
 
-SoYouWantPrizeTextPtr:
+SoYouWantPrizeText:
 	text_far _SoYouWantPrizeText
 	text_end
 
@@ -270,12 +270,12 @@ SorryNeedMoreCoinsText:
 	text_waitbutton
 	text_end
 
-PrizeRoomBagIsFullTextPtr:
+PrizeRoomBagIsFullText:
 	text_far _OopsYouDontHaveEnoughRoomText
 	text_waitbutton
 	text_end
 
-OhFineThenTextPtr:
+OhFineThenText:
 	text_far _OhFineThenText
 	text_waitbutton
 	text_end
diff --git a/engine/flag_action.asm b/engine/flag_action.asm
index dc516887..150bebab 100644
--- a/engine/flag_action.asm
+++ b/engine/flag_action.asm
@@ -43,10 +43,10 @@ FlagAction:
 	ld a, b
 	and a
 	jr z, .reset
-	cp 2
+	cp FLAG_TEST
 	jr z, .read
 
-.set
+; set
 	ld b, [hl]
 	ld a, d
 	or b
diff --git a/engine/items/inventory.asm b/engine/items/inventory.asm
index 6ac75ec7..84950a4e 100644
--- a/engine/items/inventory.asm
+++ b/engine/items/inventory.asm
@@ -118,7 +118,6 @@ RemoveItemFromInventory_::
 	jr nz, .skipMovingUpSlots
 ; if the remaining quantity is 0,
 ; remove the emptied item slot and move up all the following item slots
-.moveSlotsUp
 	ld e, l
 	ld d, h
 	inc de
diff --git a/engine/items/item_effects.asm b/engine/items/item_effects.asm
index 90853bee..12b5bd00 100644
--- a/engine/items/item_effects.asm
+++ b/engine/items/item_effects.asm
@@ -156,7 +156,7 @@ ItemUseBall:
 	dec a
 	jr nz, .notOldManBattle
 
-.oldManBattle
+; Old Man battle
 	ld hl, wGrassRate
 	ld de, wPlayerName
 	ld bc, NAME_LENGTH
@@ -645,7 +645,7 @@ ItemUseBicycle:
 	jp z, ItemUseNotTime
 	dec a ; is player already bicycling?
 	jr nz, .tryToGetOnBike
-.getOffBike
+; get off bike
 	call ItemUseReloadOverworldData
 	xor a
 	ld [wWalkBikeSurfState], a ; change player state to walking
@@ -671,13 +671,13 @@ ItemUseSurfboard:
 	ld [wWalkBikeSurfStateCopy], a
 	cp 2 ; is the player already surfing?
 	jr z, .tryToStopSurfing
-.tryToSurf
+; try to Surf
 	call IsNextTileShoreOrWater
 	jp c, SurfingAttemptFailed
 	ld hl, TilePairCollisionsWater
 	call CheckForTilePairCollisions
 	jp c, SurfingAttemptFailed
-.surf
+; surfing
 	call .makePlayerMoveForward
 	ld hl, wStatusFlags5
 	set BIT_SCRIPTED_MOVEMENT_STATE, [hl]
@@ -921,7 +921,7 @@ ItemUseMedicine:
 	ld [wHPBarOldHP], a ; current HP stored at wHPBarOldHP (2 bytes, big-endian)
 	or b
 	jr nz, .notFainted
-.fainted
+; fainted
 	ld a, [wCurItem]
 	cp REVIVE
 	jr z, .updateInBattleFaintedData
@@ -973,7 +973,7 @@ ItemUseMedicine:
 .skipComparingLSB
 	pop hl
 	jr nz, .notFullHP
-.fullHP ; if the pokemon's current HP equals its max HP
+; if the pokemon's current HP equals its max HP
 	ld a, [wCurItem]
 	cp FULL_RESTORE
 	jp nz, .healingItemNoEffect
@@ -1753,8 +1753,8 @@ ItemUsePokeFlute:
 ; OUTPUT:
 ; [wWereAnyMonsAsleep]: set to 1 if any pokemon were asleep
 WakeUpEntireParty:
-	ld de, 44
-	ld c, 6
+	ld de, PARTYMON_STRUCT_LENGTH
+	ld c, PARTY_LENGTH
 .loop
 	ld a, [hl]
 	push af
@@ -1995,7 +1995,7 @@ ItemUsePPRestore:
 	ld a, [wPPRestoreItem]
 	cp ETHER
 	jr nc, .useEther ; if Ether or Max Ether
-.usePPUp
+; use PP Up
 	ld bc, MON_PP - MON_MOVES
 	add hl, bc
 	ld a, [hl] ; move PP
diff --git a/engine/link/cable_club.asm b/engine/link/cable_club.asm
index 4a300164..6ffb2aea 100644
--- a/engine/link/cable_club.asm
+++ b/engine/link/cable_club.asm
@@ -673,7 +673,7 @@ TradeCenter_PrintPartyListNames:
 	pop de
 	inc de
 	pop hl
-	ld bc, 20
+	ld bc, SCREEN_WIDTH
 	add hl, bc
 	pop bc
 	inc c
diff --git a/engine/menus/main_menu.asm b/engine/menus/main_menu.asm
index f4d8ec03..84af085f 100644
--- a/engine/menus/main_menu.asm
+++ b/engine/menus/main_menu.asm
@@ -495,6 +495,7 @@ DisplayOptionMenu:
 	jr nz, .exitMenu
 	bit B_PAD_A, b
 	jr z, .checkDirectionKeys
+; A was pressed
 	ld a, [wTopMenuItemY]
 	cp 16 ; is the cursor on Cancel?
 	jr nz, .loop
@@ -518,7 +519,7 @@ DisplayOptionMenu:
 	jr z, .cursorInBattleStyle
 	cp 16 ; cursor on Cancel?
 	jr z, .loop
-.cursorInTextSpeed
+; cursor in Text Speed
 	bit B_PAD_LEFT, b
 	jp nz, .pressedLeftInTextSpeed
 	jp .pressedRightInTextSpeed
@@ -625,7 +626,7 @@ SetOptionsFromCursorPositions:
 	ld a, [wOptionsBattleAnimCursorX] ; battle animation cursor X coordinate
 	dec a
 	jr z, .battleAnimationOn
-.battleAnimationOff
+; battle animation Off
 	set BIT_BATTLE_ANIMATION, d
 	jr .checkBattleStyle
 .battleAnimationOn
@@ -634,7 +635,7 @@ SetOptionsFromCursorPositions:
 	ld a, [wOptionsBattleStyleCursorX] ; battle style cursor X coordinate
 	dec a
 	jr z, .battleStyleShift
-.battleStyleSet
+; battle style Set
 	set BIT_BATTLE_SHIFT, d
 	jr .storeOptions
 .battleStyleShift
diff --git a/engine/menus/naming_screen.asm b/engine/menus/naming_screen.asm
index 24b172f0..9356cc66 100644
--- a/engine/menus/naming_screen.asm
+++ b/engine/menus/naming_screen.asm
@@ -379,12 +379,13 @@ PrintNicknameAndUnderscores:
 	hlcoord 10, 3
 	ld a, [wNamingScreenType]
 	cp NAME_MON_SCREEN
-	jr nc, .pokemon1
-	ld b, 7 ; player or rival max name length
-	jr .playerOrRival1
-.pokemon1
-	ld b, 10 ; pokemon max name length
-.playerOrRival1
+	jr nc, .pokemon
+; player or rival
+	ld b, PLAYER_NAME_LENGTH - 1
+	jr .gotUnderscoreCount
+.pokemon
+	ld b, NAME_LENGTH - 1
+.gotUnderscoreCount
 	ld a, $76 ; underscore tile id
 .placeUnderscoreLoop
 	ld [hli], a
@@ -394,13 +395,15 @@ PrintNicknameAndUnderscores:
 	cp NAME_MON_SCREEN
 	ld a, [wNamingScreenNameLength]
 	jr nc, .pokemon2
-	cp 7 ; player or rival max name length
-	jr .playerOrRival2
+; player or rival
+	cp PLAYER_NAME_LENGTH - 1
+	jr .checkEmptySpaces
 .pokemon2
-	cp 10 ; pokemon max name length
-.playerOrRival2
-	jr nz, .emptySpacesRemaining
-	; when all spaces are filled, force the cursor onto the ED tile
+	cp NAME_LENGTH - 1
+.checkEmptySpaces
+	jr nz, .placeRaisedUnderscore ; jump if empty spaces remain
+	; when all spaces are filled, force the cursor onto the ED tile,
+	; and keep the last underscore raised
 	call EraseMenuCursor
 	ld a, $11 ; "ED" x coord
 	ld [wTopMenuItemX], a
@@ -408,11 +411,10 @@ PrintNicknameAndUnderscores:
 	ld [wCurrentMenuItem], a
 	ld a, [wNamingScreenType]
 	cp NAME_MON_SCREEN
-	ld a, 9 ; keep the last underscore raised
-	jr nc, .pokemon3
-	ld a, 6 ; keep the last underscore raised
-.pokemon3
-.emptySpacesRemaining
+	ld a, NAME_LENGTH - 2
+	jr nc, .placeRaisedUnderscore
+	ld a, PLAYER_NAME_LENGTH - 2
+.placeRaisedUnderscore
 	ld c, a
 	ld b, $0
 	hlcoord 10, 3
diff --git a/engine/menus/party_menu.asm b/engine/menus/party_menu.asm
index f2688b52..15fd62be 100644
--- a/engine/menus/party_menu.asm
+++ b/engine/menus/party_menu.asm
@@ -90,7 +90,7 @@ RedrawPartyMenu_::
 	jr nz, .placeMoveLearnabilityString
 	ld de, .notAbleToLearnMoveText
 .placeMoveLearnabilityString
-	ld bc, 20 + 9 ; down 1 row and right 9 columns
+	ld bc, SCREEN_WIDTH + 9 ; 1 row down and 9 columns right
 	push hl
 	add hl, bc
 	call PlaceString
@@ -102,7 +102,7 @@ RedrawPartyMenu_::
 	pop hl
 	pop de
 	inc de
-	ld bc, 2 * 20
+	ld bc, 2 * SCREEN_WIDTH
 	add hl, bc
 	pop bc
 	inc c
diff --git a/engine/menus/pokedex.asm b/engine/menus/pokedex.asm
index 3e4096bc..3d2fcbca 100644
--- a/engine/menus/pokedex.asm
+++ b/engine/menus/pokedex.asm
@@ -105,7 +105,7 @@ HandlePokedexSideMenu:
 	jr z, .choseCry
 	dec a
 	jr z, .choseArea
-.choseQuit
+; chose Quit
 	ld b, 1
 .exitSideMenu
 	pop af
@@ -286,7 +286,7 @@ HandlePokedexListMenu:
 	call HandleMenuInput
 	bit B_PAD_B, a
 	jp nz, .buttonBPressed
-.checkIfUpPressed
+; check if Up pressed
 	bit B_PAD_UP, a
 	jr z, .checkIfDownPressed
 .upPressed ; scroll up one row
@@ -299,7 +299,7 @@ HandlePokedexListMenu:
 .checkIfDownPressed
 	bit B_PAD_DOWN, a
 	jr z, .checkIfRightPressed
-.downPressed ; scroll down one row
+; Down pressed, scroll down one row
 	ld a, [wDexMaxSeenMon]
 	cp 7
 	jp c, .loop ; can't if the list is shorter than 7
@@ -314,7 +314,7 @@ HandlePokedexListMenu:
 .checkIfRightPressed
 	bit B_PAD_RIGHT, a
 	jr z, .checkIfLeftPressed
-.rightPressed ; scroll down 7 rows
+; Right pressed, scroll down 7 rows
 	ld a, [wDexMaxSeenMon]
 	cp 7
 	jp c, .loop ; can't if the list is shorter than 7
@@ -332,7 +332,7 @@ HandlePokedexListMenu:
 .checkIfLeftPressed ; scroll up 7 rows
 	bit B_PAD_LEFT, a
 	jr z, .buttonAPressed
-.leftPressed
+; Left pressed
 	ld a, [wListScrollOffset]
 	sub 7
 	ld [wListScrollOffset], a
@@ -593,8 +593,8 @@ HeightWeightText:
 	db   "HT  ?′??″"
 	next "WT   ???lb@"
 
-; XXX does anything point to this?
-PokeText:
+; leftover from JPN Pokedex, where species have the suffix "Pokemon"
+PokeText: ; unreferenced
 	db "#@"
 
 ; horizontal line that divides the pokedex text description from the rest of the data
diff --git a/engine/menus/start_sub_menus.asm b/engine/menus/start_sub_menus.asm
index ec10dd11..817dceb8 100644
--- a/engine/menus/start_sub_menus.asm
+++ b/engine/menus/start_sub_menus.asm
@@ -340,7 +340,7 @@ StartMenu_Item::
 	ld a, [wCurItem]
 	cp BICYCLE
 	jp z, .useOrTossItem
-.notBicycle1
+; not Bicycle
 	ld a, USE_TOSS_MENU_TEMPLATE
 	ld [wTextBoxID], a
 	call DisplayTextBoxID
@@ -370,14 +370,14 @@ StartMenu_Item::
 	call CopyToStringBuffer
 	ld a, [wCurItem]
 	cp BICYCLE
-	jr nz, .notBicycle2
+	jr nz, .notBicycle
 	ld a, [wStatusFlags6]
 	bit BIT_ALWAYS_ON_BIKE, a
 	jr z, .useItem_closeMenu
 	ld hl, CannotGetOffHereText
 	call PrintText
 	jp ItemMenuLoop
-.notBicycle2
+.notBicycle
 	ld a, [wCurrentMenuItem]
 	and a
 	jr nz, .tossItem
diff --git a/engine/menus/swap_items.asm b/engine/menus/swap_items.asm
index 2d506ce2..dc54b645 100644
--- a/engine/menus/swap_items.asm
+++ b/engine/menus/swap_items.asm
@@ -76,7 +76,7 @@ HandleItemListSwapping::
 	ld a, [hli]
 	cp b
 	jr z, .swapSameItemType
-.swapDifferentItems
+; swap different items
 	ldh [hSwapItemID], a ; save second item ID
 	ld a, [hld]
 	ldh [hSwapItemQuantity], a ; save second item quantity
diff --git a/engine/movie/credits.asm b/engine/movie/credits.asm
index b1ca7c91..77484a80 100644
--- a/engine/movie/credits.asm
+++ b/engine/movie/credits.asm
@@ -6,10 +6,10 @@ HallOfFamePC:
 	call DisableLCD
 	ld hl, vFont
 	ld bc, ($80 tiles) / 2
-	call ZeroMemory
+	call ShiftFontColorIndex
 	ld hl, vChars2 tile $60
 	ld bc, ($20 tiles) / 2
-	call ZeroMemory
+	call ShiftFontColorIndex
 	ld hl, vChars2 tile $7e
 	ld bc, TILE_SIZE
 	ld a, $ff ; solid black
@@ -33,7 +33,7 @@ HallOfFamePC:
 	ld [wNumCreditsMonsDisplayed], a
 	jp Credits
 
-FadeInCreditsText:
+FadeInCredits:
 	ld hl, HoFGBPalettes
 	ld b, 4
 .loop
@@ -145,15 +145,18 @@ CreditsCopyTileMapToVRAM:
 	ldh [hAutoBGTransferEnabled], a
 	jp Delay3
 
-ZeroMemory:
-; zero bc bytes at hl
+ShiftFontColorIndex:
+; Zero every second byte at hl, writing a total of bc bytes.
+; When used on VRAM font characters that contain only black and white shades,
+; it shifts the color index: black -> light gray, allowing palette-controlled
+; text fade-in during the Credits roll, while the black bars remain solid.
 	ld [hl], 0
 	inc hl
 	inc hl
 	dec bc
 	ld a, b
 	or c
-	jr nz, ZeroMemory
+	jr nz, ShiftFontColorIndex
 	ret
 
 FillFourRowsWithBlack:
@@ -215,7 +218,7 @@ Credits:
 	pop de
 	jr .nextCreditsCommand
 .fadeInTextAndShowMon
-	call FadeInCreditsText
+	call FadeInCredits
 	ld c, 90
 	jr .next1
 .showTextAndShowMon
@@ -225,7 +228,7 @@ Credits:
 	call DisplayCreditsMon
 	jr .nextCreditsScreen
 .fadeInText
-	call FadeInCreditsText
+	call FadeInCredits
 	ld c, 120
 	jr .next2
 .showText
@@ -254,7 +257,7 @@ Credits:
 	hlcoord 4, 9
 	inc de
 	call PlaceString
-	jp FadeInCreditsText
+	jp FadeInCredits
 
 TheEndTextString:
 ; "T H E  E N D"
diff --git a/engine/overworld/auto_movement.asm b/engine/overworld/auto_movement.asm
index bed2ffb9..13d30cca 100644
--- a/engine/overworld/auto_movement.asm
+++ b/engine/overworld/auto_movement.asm
@@ -1,6 +1,6 @@
 PlayerStepOutFromDoor::
-	ld hl, wStatusFlags5 ; should this be wMovementFlags?
-	res BIT_EXITING_DOOR, [hl]
+	ld hl, wStatusFlags5
+	res BIT_UNKNOWN_5_1, [hl]
 	call IsPlayerStandingOnDoorTile
 	jr nc, .notStandingOnDoor
 	ld a, PAD_SELECT | PAD_START | PAD_CTRL_PAD
diff --git a/engine/overworld/missable_objects.asm b/engine/overworld/missable_objects.asm
index 1660a894..8ea79980 100644
--- a/engine/overworld/missable_objects.asm
+++ b/engine/overworld/missable_objects.asm
@@ -178,10 +178,10 @@ MissableObjectFlagAction:
 	ld a, b
 	and a
 	jr z, .reset
-	cp 2
+	cp FLAG_TEST
 	jr z, .read
 
-.set
+; set
 	ld a, [hl]
 	ld b, a
 	ld a, d
diff --git a/engine/overworld/movement.asm b/engine/overworld/movement.asm
index 8d02f0fe..a353c4f1 100644
--- a/engine/overworld/movement.asm
+++ b/engine/overworld/movement.asm
@@ -140,7 +140,7 @@ UpdateNPCSprite:
 	ld b, a
 	ld a, [wFontLoaded]
 	bit BIT_FONT_LOADED, a
-	jp nz, notYetMoving
+	jp nz, NotYetMoving
 	ld a, b
 	cp $2
 	jp z, UpdateSpriteMovementDelay  ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] == 2
@@ -389,14 +389,15 @@ UpdateSpriteMovementDelay:
 	jr .moving
 .tickMoveCounter
 	dec [hl]                ; x#SPRITESTATEDATA2_MOVEMENTDELAY
-	jr nz, notYetMoving
+	jr nz, NotYetMoving
 .moving
 	dec h
 	ldh a, [hCurrentSpriteOffset]
 	inc a
 	ld l, a
 	ld [hl], $1             ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = 1 (mark as ready to move)
-notYetMoving:
+	; fallthrough
+NotYetMoving:
 	ld h, HIGH(wSpriteStateData1)
 	ldh a, [hCurrentSpriteOffset]
 	add SPRITESTATEDATA1_ANIMFRAMECOUNTER
@@ -411,7 +412,7 @@ MakeNPCFacePlayer:
 ; disabled. This is only done when rubbing the S.S. Anne captain's back.
 	ld a, [wStatusFlags3]
 	bit BIT_NO_NPC_FACE_PLAYER, a
-	jr nz, notYetMoving
+	jr nz, NotYetMoving
 	res BIT_FACE_PLAYER, [hl]
 	ld a, [wPlayerDirection]
 	bit PLAYER_DIR_BIT_UP, a
@@ -435,7 +436,7 @@ MakeNPCFacePlayer:
 	add $9
 	ld l, a
 	ld [hl], c              ; [x#SPRITESTATEDATA1_FACINGDIRECTION]: set facing direction
-	jr notYetMoving
+	jr NotYetMoving
 
 InitializeSpriteStatus:
 	ld [hl], $1   ; [x#SPRITESTATEDATA1_MOVEMENTSTATUS] = ready
diff --git a/engine/overworld/pathfinding.asm b/engine/overworld/pathfinding.asm
index 878ca07d..d6e0d009 100644
--- a/engine/overworld/pathfinding.asm
+++ b/engine/overworld/pathfinding.asm
@@ -94,7 +94,7 @@ CalcPositionOfPlayerRelativeToNPC:
 	ld a, [hli] ; NPC sprite screen Y position in pixels
 	call CalcDifference
 	jr nc, .NPCSouthOfOrAlignedWithPlayer
-.NPCNorthOfPlayer
+; NPC north of player
 	push hl
 	ld hl, hNPCPlayerRelativePosFlags
 	bit BIT_PLAYER_LOWER_Y, [hl]
@@ -122,7 +122,7 @@ CalcPositionOfPlayerRelativeToNPC:
 	ld a, [hl] ; NPC sprite screen X position in pixels
 	call CalcDifference
 	jr nc, .NPCEastOfOrAlignedWithPlayer
-.NPCWestOfPlayer
+; NPC west of player
 	push hl
 	ld hl, hNPCPlayerRelativePosFlags
 	bit BIT_PLAYER_LOWER_X, [hl]
diff --git a/engine/overworld/push_boulder.asm b/engine/overworld/push_boulder.asm
index 2328b07a..5e7393d2 100644
--- a/engine/overworld/push_boulder.asm
+++ b/engine/overworld/push_boulder.asm
@@ -43,7 +43,7 @@ TryPushingBoulder::
 	jr z, .pushBoulderLeft
 	cp SPRITE_FACING_RIGHT
 	jr z, .pushBoulderRight
-.pushBoulderDown
+; push boulder down
 	bit B_PAD_DOWN, b
 	ret z
 	ld de, PushBoulderDownMovementData
diff --git a/engine/pokemon/add_mon.asm b/engine/pokemon/add_mon.asm
index 455221ce..c92acfcb 100644
--- a/engine/pokemon/add_mon.asm
+++ b/engine/pokemon/add_mon.asm
@@ -375,7 +375,7 @@ _MoveMon::
 .copySpecies
 	ld [hli], a          ; write new mon ID
 	ld [hl], $ff         ; write new sentinel
-.findMonDataDest
+; find mon data dest
 	ld a, [wMoveMonType]
 	dec a
 	ld hl, wPartyMons
@@ -457,7 +457,7 @@ _MoveMon::
 	ld bc, NAME_LENGTH
 	call CopyData
 	ld a, [wMoveMonType]
-.findNickDest
+; find nick dest
 	cp PARTY_TO_DAYCARE
 	ld de, wDayCareMonName
 	jr z, .findNickSrc
diff --git a/engine/pokemon/load_mon_data.asm b/engine/pokemon/load_mon_data.asm
index d90b9cd8..87a2be8b 100644
--- a/engine/pokemon/load_mon_data.asm
+++ b/engine/pokemon/load_mon_data.asm
@@ -31,7 +31,7 @@ LoadMonData_::
 	ld hl, wEnemyMons
 	jr z, .getMonEntry
 
-	cp 2
+	cp BOX_DATA
 	ld hl, wBoxMons
 	ld bc, BOXMON_STRUCT_LENGTH
 	jr z, .getMonEntry