Best Practices for Self-Documenting Code and Effective Commenting, Slides of Computer Engineering and Programming

Download Best Practices for Self-Documenting Code and Effective Commenting and more Slides Computer Engineering and Programming in PDF only on Docsity!

1

Self-Documenting

Code

2

Programming Style as Documentation

Poor Documentation resulting from Bad Programming Style

4

Self-Documenting Code Guidelines

 Use specific, easily-understandable names

 Do not use ‘magic’ numbers

 Use data abstraction whenever complicated data is

required

 Minimize loop nesting and other control structure

complexity

 Use good and consistent program layout

 Avoid clever, but difficult-to-understand,

programming tricks

5

Effective Comments

Mystery Routine Number One

7

Effective Comments

Mystery Routine Number Three

8

Easy-to-Maintain Commenting Style

module: GIGATRON.C author: Dwight K. Coder date: July 4, 2014 purpose: Routines to control the twenty-first century’s code evaluation tool. The entry point to these routines is the EvaluateCode() routine at the bottom of this file.

************************************************/

10

Better Comments would be...

 /* Find ‘$’ in InputStr */

• This gives the goal

 /* find the command-word terminator */

• This gives the intention
• Think of the name of the coding fragment

11

Better still…

Good coding with good comments

13

Good Commenting Techniques

 Include other facts about the code: algorithm source, interface assumptions, limitations, etc.

 Describe the purpose of each file

 List the author’s name and phone number

Above all…

 Try to improve code so that less comments will be needed

 Write comments only for something that the code cannot say

14

The Bottom Line

Imagine yourself having to modify this

program…one year later.

Are you going to love or hate the person

writing the code and the comments?!?!