Page 219 - DCAP305_PRINCIPLES_OF_SOFTWARE_ENGINEERING

Unit 10: Coding Standards

• Avoid reusing names for different elements, such as a routine called ProcessSales() and Notes
a variable called iProcessSales.
• Avoid homonyms when naming elements to prevent confusion during code reviews, such
as write and right.

• When naming elements, avoid using commonly misspelled words. Also, be aware of
differences that exist between American and British English, such as color/colour and
check/cheque.
• Avoid using typographical marks to identify data types, such as $ for strings or % for
integers.
Comments
Software documentation exists in two forms, external and internal. External documentation is
maintained outside of the source code, such as specifications, help files, and design documents.
Internal documentation is composed of comments that developers write within the source code
at development time.
One of the challenges of software documentation is ensuring that the comments are maintained
and updated in parallel with the source code. Although properly commenting source code
serves no purpose at run time, it is invaluable to a developer who must maintain a particularly
intricate or cumbersome piece of software.

Following are recommended commenting techniques:
• When modifying code, always keep the commenting around it up to date.
• At the beginning of every routine, it is helpful to provide standard, boilerplate comments,
indicating the routine’s purpose, assumptions, and limitations. A boilerplate comment
should be a brief introduction to understand why the routine exists and what it can do.
• Avoid adding comments at the end of a line of code; end-line comments make code more
difficult to read. However, end-line comments are appropriate when annotating variable
declarations. In this case, align all end-line comments at a common tab stop.
• Avoid using clutter comments, such as an entire line of asterisks. Instead, use white space
to separate comments from code.
• Avoid surrounding a block comment with a typographical frame. It may look attractive,
but it is difficult to maintain.
• Prior to deployment, remove all temporary or extraneous comments to avoid confusion
during future maintenance work.

• If you need comments to explain a complex section of code, examine the code to determine
if you should rewrite it. If at all possible, do not document bad code—rewrite it. Although
performance should not typically be sacrificed to make the code simpler for human
consumption, a balance must be maintained between performance and maintainability.
• Use complete sentences when writing comments. Comments should clarify the code, not
add ambiguity.
• Comment as you code, because most likely there would not be time to do it later. Also,
should you get a chance to revisit code you have written, that which is obvious today
probably would not be obvious six weeks from now.
• Avoid the use of superfluous or inappropriate comments, such as humorous sidebar
remarks.
• Use comments to explain the intent of the code. They should not serve as inline translations
of the code.

LOVELY PROFESSIONAL UNIVERSITY 213