US Election Assistance Commission - Voluntary Voting System Guidelines Vote
EAC Home
Introduction
View Guidelines
View Comments
Glossary

View Comments

Section CommentsGeneral CommentsGlossary Comments
 
Name :   Scott Hunsaker
Organization :   Hart Intercivic
Post Date :   9/30/2005

Section Comments
Section :  4.2.7
Page no. :  4-7
Line no.:  
Comment :  4.2.7.a.

Comment:
All modules shall contain
headers…

Recommended change:
All modules shall contain
common headers containing
comments that enhance the
understanding and readability
of the module if the function of
the module is not readily
apparent from the code and/or
comments. The requirements listed in
items 1 through 6 should be
identified as guidelines.

Rationale:
Current state-of-the-art coding
practice is to write 'Self-
Documenting Code'
[McConnell ch. 19]. Other
header content should be
consistently applied according
to project coding conventions
as required in Volume I Section
4.2.6. Mandating specific
header requirements in the
existing Standard creates an
environment that is too rigid
and does not allow for the use
of evolving state-of-the-art
documentation tools.