|
H.4 Documenting Routine Headers in SheerPower |
Documenting Routine Headers in SheerPower
When documenting routines in SheerPower, always clearly describe what the routine does, what it expects upon entry, and what it returns or affects upon exit. Good documentation helps you—and everyone else—quickly understand and maintain your code.
Why Routine Documentation Matters
- Clarity: Immediately communicates routine purpose.
- Maintainability: Makes routines easy to modify.
- Consistency: Standardizes documentation style.
Common Mistakes to Avoid
- Leaving out key entry or exit variables.
- Using inconsistent formats or styles.
- Allowing documentation to become outdated.
- Writing overly long or vague descriptions.
Example of Poor Routine Documentation
This header is incomplete and misses important entry variables:
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
! c a l c u l a t e _ t o t a l
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!
! Brief description:
! Calculates the total tutorials.
!
! Expected on entry:
! (Missing entry variables!)
!
! Locals used:
! total
!
! Results on exit:
! Returns the total calculated.
!
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
routine calculate_total
local total
total = tutorial_counter
return total
end routine
Without clear entry variables, you must read the routine to understand what it needs—causing confusion and wasted time.
Example of Good Routine Documentation
This routine is properly documented, clear, and informative:
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
! c a l c u l a t e _ t o t a l
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!
! Brief description:
! Calculates the total number of tutorials processed.
!
! Expected on entry:
! tutorial_counter = total tutorials so far
! current_part = current output file number
!
! Locals used:
! total = temporary variable for computed total
!
! Results on exit:
! Returns the total number of tutorials processed
!
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
routine calculate_total
local total
total = tutorial_counter
return total
end routine
Quick Documentation Checklist
- Starts and ends with clear delimiter lines
- Routine name is styled prominently and clearly
- Has a brief, informative description
- Lists all expected entry variables and states
- Lists local variables used (or explicitly notes none)
- States results returned or affected on exit
Conclusion
Properly documented routine headers improve clarity, consistency, and maintenance. Always document entry and exit states, use a consistent format, and update headers as code changes.
|
Hide Description
|
|
|
Enter or modify the code below, and then click on RUN |
|
Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use. |
