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.b

Comment:
Descriptive comments shall be
provided to identify objects and
data types. All variables shall
have comments at the point of
declaration clearly explaining
their use.

Recommended change:
Objects, data types, and
variables should have
comments at the point of
declaration clearly explaining
their use when required to
enhance the readability and
intelligibility of the program.

Rationale:
This requirement should be
identified as a guideline and is
effectively defined by the
requirement in 4.2.5.a
"…variable names shall be
chosen so as to enhance the
readability and intelligibility of
the program." Adding an
unnecessary comment to an
already descriptive name
detracts from the value of the
comments in general.
[McConnell Ch 9]