Programming Style: - Who Reads Your Code?
Programming Style: - Who Reads Your Code?
Programming Style: - Who Reads Your Code?
CS 217
Programming Style
• Who reads your code?
compiler
other programmers
• Which one cares about style?
typedef struct{double x,y,z}vec;vec U,black,amb={.02,.02,.02};struct sphere{
vec cen,color;double rad,kd,ks,kt,kl,ir}*s,*best,sph[]={0.,6.,.5,1.,1.,1.,.9,
.05,.2,.85,0.,1.7,-1.,8.,-.5,1.,.5,.2,1.,.7,.3,0.,.05,1.2,1.,8.,-.5,.1,.8,.8,
1.,.3,.7,0.,0.,1.2,3.,-6.,15.,1.,.8,1.,7.,0.,0.,0.,.6,1.5,-3.,-3.,12.,.8,1.,
1.,5.,0.,0.,0.,.5,1.5,};yx;double u,b,tmin,sqrt(),tan();double vdot(A,B)vec A
,B;{return A.x*B.x+A.y*B.y+A.z*B.z;}vec vcomb(a,A,B)double a;vec A,B;{B.x+=a*
A.x;B.y+=a*A.y;B.z+=a*A.z;return B;}vec vunit(A)vec A;{return vcomb(1./sqrt(
vdot(A,A)),A,black);}struct sphere*intersect(P,D)vec P,D;{best=0;tmin=1e30;s=
sph+5;while(s--sph)b=vdot(D,U=vcomb(-1.,P,s-cen)),u=b*b-vdot(U,U)+s-rad*s -
rad,u=u0?sqrt(u):1e31,u=b-u1e-7?b-u:b+u,tmin=u=1e-7&&u<tmin?best=s,u:
tmin;return best;}vec trace(level,P,D)vec P,D;{double d,eta,e;vec N,color;
struct sphere*s,*l;if(!level--)return black;if(s=intersect(P,D));else return
amb;color=amb;eta=s-ir;d= -vdot(D,N=vunit(vcomb(-1.,P=vcomb(tmin,D,P),s-cen
)));if(d<0)N=vcomb(-1.,N,black),eta=1/eta,d= -d;l=sph+5;while(l--sph)if((e=l -
kl*vdot(N,U=vunit(vcomb(-1.,P,l-cen))))0&&intersect(P,U)==l)color=vcomb(e ,l-
color,color);U=s-color;color.x*=U.x;color.y*=U.y;color.z*=U.z;e=1-eta* eta*(1-
d*d);return vcomb(s-kt,e0?trace(level,P,vcomb(eta,D,vcomb(eta*d-sqrt
(e),N,black))):black,vcomb(s-ks,trace(level,P,vcomb(2*d,N,D)),vcomb(s-kd,
color,vcomb(s-kl,U,black))));}main(){printf("%d %d\n",32,32);while(yx<32*32)
U.x=yx%32-32/2,U.z=32/2-yx++/32,U.y=32/2/tan(25/114.5915590261),U=vcomb(255.,
trace(3,black,vunit(U)),black),printf("%.0f %.0f %.0f\n",U);}
1
Programming Style
• Why does programming style matter?
Bugs are often created due to misunderstanding of programmer
– What does this variable do?
– How is this function called?
Good code == human readable code
return 0;
}
Structure
• Convey structure with layout and indentation
use white space freely
e.g., to separate code into paragraphs
use indentation to emphasize structure
use editor’s autoindent facility
break long lines at logical places
e.g., by operator precedence
line up parallel structures
alpha = angle(p1, p2, p3);
beta = angle(p1, p2, p3);
gamma = angle(p1, p2, p3);
2
Structure
• Convey structure with modules
separate modules in different files
e.g., sort.c versus stringarray.c
simple, atomic operations in different functions
e.g., ReadStrings, WriteStrings, SortStrings, etc.
separate distinct ideas within same function
#include “stringarray.h”
int main()
{
char *strings[MAX_STRINGS];
int nstrings;
return 0;
}
Structure
• Convey structure with spacing and indenting
implement multiway branches with if … else if … else
emphasize that only one action is performed
avoid empty then and else actions
handle default action, even if can’t happen (use assert(0))
avoid continue; minimize use of break and return
avoid complicated nested structures
3
Conventions
• Follow consistent naming style
use descriptive names for globals and functions
e.g., WriteStrings, iMaxIterations, pcFilename
use concise names for local variables
e.g., i (not arrayindex) for loop variable
use case judiciously
e.g., PI, MAX_STRINGS (reserve for constants)
use consistent style for compound names
e.g., writestrings, WriteStrings, write_strings
Documentation
• Documentation
comments should add new information
i = i + 1; /* add one to i */
comments must agree with the code
comment procedural interfaces liberally
comment sections of code, not lines of code
master the language and its idioms; let the code speak for itself
4
Example: Command Line Parsing
/***************************************/
/* Parse command line arguments */
/* Input is argc and argv from main */
/* Return 1 for success, 0 for failure */
/***************************************/
/* Return success */
return 1;
}
Scope
• The scope of an identifier says where it can be used
stringarray.h
extern void ReadStrings(char **strings, int *nstrings, int maxstrings, FILE *fp);
extern void WriteStrings(char **strings, int nstrings, FILE *fp);
extern void SortStrings(char **strings, int nstrings);
sort.c
#include “stringarray.h”
int main()
{
char *strings[MAX_STRINGS];
int nstrings;
return 0;
}
5
Definitions and Declarations
• A declaration announces the properties of an identifier
and adds it to current scope
extern int nstrings;
extern char **strings;
extern void WriteStrings(char **strings, int nstrings);
int nstrings = 0;
char *strings[128];
void WriteStrings(char **strings, int nstrings)
{
…
}
6
static versus extern
Global Variables
• Functions can use global variables declared
outside and above them within same file
int stack[100];
int main() {
. . . stack is in scope
}
int sp;
void push(int x) {
. . . stack, sp is in scope
}
7
Local Variables & Parameters
• Functions can declare and define local variables
created upon entry to the function
destroyed upon return
• Function parameters behave like initialized local variables
values copied into “local variables”
int CompareStrings(char *s1, char *s2) int CompareStrings(char *s1, char *s2)
{ {
char *p1 = s1; while (*s1 && *s2) {
char *p2 = s2; if (*s1 < *s2) return -1;
else if (*s1 > *s2) return 1;
while (*p1 && *p2) { s1++;
if (*p1 < *p2) return -1; s2++;
else if (*p1 > *p2) return 1; }
p1++;
p2++; return 0;
} }
return 0;
}
t = x; t = *x;
x = y;
No! *x = *y;
Yes
y = t; *y = t;
} }
x 3 x 7 x x
y 7 y 3 y y
a 3 a 3 a 3 a 7
b 7 b 7 b 7 b 3
8
Local Variables & Parameters
• Function parameters and local declarations
“hide” outer-level declarations
int x, y;
. . .
f(int x, int a) {
int b;
. . .
y = x + a*b;
if (. . .) {
int a;
. . .
y = x + a*b;
}
}
f(int x) {
int x; error!
. . .
}
9
Scope Example
int a, b; Output
main (void) { 3 4
a = 1; b = 2;
f(a); 3 2
print(a, b); 1 5
}
void f(int a) {
a = 3;
{
int b = 4;
print(a, b);
}
print(a, b);
b = 5;
}
10
Summary
• Programming style is important for good code
Structure
Conventions
Documentation
Scope
11