pdf, 18 pages - Computer Science
Contents
1. As shown in the example a row of double stars along the left edge serves to visually set the block comment apart from everything else When approaching a large program for the first time the reader will look only at the block comments in an attempt to get an overview of the program These comments may often be used when skimming a program in an attempt to find the section of relevant code to examine more carefully The row of double stars helps when scanning thousands of lines of code Insert exactly three blank lines before the block comment to set it off from the preceding routine Again this is just a visual aid to the eye in finding routine boundaries Some people suggest using a long line full of asterisks to set off the block comment Some people go to the trouble of surrounding the block comment in boxes made out of asterisks I feel that level of art is overkill it is too difficult to maintain and can be visually distracting Notice that there is a single blank between the asterisks and the text of the comment and that the last line of the comment serves as a sort of blank line between the text of the comment and the first line of the subroutine The first line of the block comment gives the name of the subroutine and its parameters The parameters are given by name Parameter types are not given here since they are listed in the first line of the subroutine and repeating them in the block comment becomes a point of possible incon2. Every else should appear on a line by itself and will be preceded by a closing brace and a space and followed by a space and an opening brace as shown above Line up the parts of the if else as shown above Put the statements in the then and else clauses on separate lines do not put the statements on the same line as the if or else if nextToken t advance wrong else syntaxError t nextToken wrong Rule 10 Format if elseif clauses specially OK to Copy and Distribute Page 11 Sometimes a sequence of nested if statements would be more properly programmed using an if elseif construct but unfortunately C does not have such a construct This happens when there are a series of tests to be performed sequentially and exactly one will be satisfied Here is an example if c EOF wrong return LX_EOF else if isalpha c return LX_ALPHA else if isdigit c return LX_DIGIT else printError When code like this occurs it is better to format it as follows This is how to code an if elseif statement in C if c EOF right return LX_EOF else if isalpha c return LX_ALPHA else if isdigit c return LX_DIGIT else printError Rule 11 Surround all operators by a space Operators are very important and using a single space on either si
3. Occasionally you will catch only a hint of a problem with your code Never ignore a problem You must learn to love problems to be a good programmer If you have the slightest scent of a bug you must chase after it like a hound after the fox Intuitions and suspicions can be forgotten so easily Write it down on your list If you have the slightest whiff of a bug check it out fully This may be your only chance to find that bug and you don t want to miss it Never say to yourself I can ignore that because I ll take care of it later Do not ever leave a bug in your program Do not ever put off fixing your code Perhaps you say This is in a section of code I am not working on right now Perhaps you think that it is such an obvious bug that you will be forced to deal with it anyway when you are debugging later No matter what kind of lies you may be tempted to tell yourself never let a problem in your code go untended At least write it down on your list so that you will be sure to attend to it later A particularly nasty form of procrastination occurs when you say Pl write the code this way since it would take too long to write it more carefully I just want to get something working first and I ll come back and improve this code later It is much wiser to do it right the first time and in the long run it will always save time If you do it right the first time you will sleep much easier at night If you skimp and cheat and write
4. assumed that if the reader wants to know how the subroutine works he will read the code itself There is no value in repeating what the code does in the block comment since the code is right there anyway At worst the comment can be incorrect or misleading and can cause the reader to misinterpret the code However if the algorithm is sufficiently complex it may be a good idea to comment on it This should be done in a separate paragraph in the block comment Rule 2 Do not put opening braces on a line by themselves Note that the opening brace for the subroutine occurs on the same line as the subroutine name and parameter list It follows the closing parenthesis and is separated by exactly one blank The opening brace for the if statement also follows a closing parenthesis and again a single space is used to set it off The rule eliminates a lot of blank lines these blank lines waste space on the screen they are visually distracting and they lower the impact of truly blank lines inserted for clarity Rule 3 Always indent in increments of 2 spaces Indent consistently If you are indenting by increments of two spaces don t indent some lines by other amounts DE wietetes right IE oet x 7 DE E wrong EE aeeie x 7 Why two spaces and not another amount First one space is not enough since our eyes are so used to seeing single spaces The visual effect is not strong enough With one sp
5. bytes Rule 7 Always uses braces in if for and while loops Use braces even if there is only one statement in the body and the braces are not strictly necessary The primary motivation is consistency With only a single statement there are two options you can either include braces or not Since you will be using braces in other cases i e when the body has two or more statements you might as well use braces always while wrong KX wee while right X ee3 One general principle of finding a good coding style is when there are two ways to code the same thing determine which is the more general way and then always code in that style Here the goal is to have all while loops look the same regardless of how many statements the body contains The closing brace serves to mark the end point of the loop or if statement This point is a very important place and needs some symbol to mark it Without the braces as in the following example the location of the end of the loop is not as clear while amp amp wrong see if amp amp sua if amp amp eee amp amp see Z a while amp amp right df if amp amp eee if amp amp a amp amp se z st Another reason for using braces is that it makes it easier to insert an additional statement into a loop or if statement without making a mi
6. code that you know could be better you will loathe yourself and have nightmares all night Don t write code that you know is not the best it could be What is a coding style Of course a compiler will scan your program so it must conform to the formal definition of the language and the compiler will check this mechanically but all programming languages allow a great deal of flexibility in exactly how the program is written For example how will you indent your if statements How much will you comment and what will the comments look like It is these issues that separate well written correct programs from poorly written but still correct programs In the remainder of this document I list several rules which if followed will make you a better coder OK to Copy and Distribute Page 6 Rule 1 Use a block comment for every function or procedure Each subroutine should be preceded by a block comment By subroutine I mean procedures and functions A block comment describes the nature of the subroutine its name its arguments and its returned value Block comments occur only in front of each subroutine and not within subroutines match t k k This routine ensures that the next token is a t If so it scans xx it and advances to the next token if not it prints an error message and halts execution void match token t if nextToken t advance else syntaxError t nextToken
7. is to make sure that you exercise every single line of code at least once After all if your test data fails to ever execute some single line of source code then any bug in that line will not have been discovered It may occasionally be tempting to avoid testing one or two lines of code because they look so simple and straightforward that nothing could possibly go wrong Some code might seem self evidently correct Only amateur programmers ever fall for this logic for the simple reason that if you could always see bugs by looking at the code there would never be any need to test the code You must execute every line of code For if statements this means that you must run a test in which the then statements are executed and you must also run a test in which the else statements are executed If there are no else statements this means you must run tests in which the if condition is true sometimes and tests where it is false sometimes You must make sure your if statement is correct If Boolean conditions can be satisfied several ways as in the following example then you must exercise each possibility individually In the following example you must run cases where each of the three sub conditions is true if char EOF i gt MAX _ID LENGTH symbolTableFull printf error else For while loops you should run a test case in which the loop body is executed zero times e t
8. lt stdio h gt include lexer h char tokenBuffer MAX ID LENGTH Buffer for storing current token int bufferIndex Next unused tokenBuffer position Routines in this file token getToken token checkReserved void lexicalError char message void initBuffer File Name Each file should start with a block comment describing what is in the file The first line should be the normal file name Sometimes files get renamed so this may not be the actual file name but it serves to identify the file when it is viewed If the program has a formal name or title this would also go on line one Author Information The second line after a blank line should include the original author s name and the date the file was created Subsequent lines should list the names of all people who have modified the file and the dates Do not ever modify someone else s program without putting your name and the date into the file Once you modify the program the responsibility for its correctness is yours Leaving someone else s name as the last person who modified the file is considered fraudulent and dastardly Program Description The block comment should then describe the program in general terms Often this will contain a reference to an external document as in this example but it is also okay to include the user s manual directly in the file for small or medium sized systems After all this is probably the s
9. over the span of three or four statements can be given single letter names to indicate their temporary nature Here is an example using these conventions if atEnd right printError OK to Copy and Distribute Page 16 else t getToken c tokenBuffer 1 if isLetter c gotLetter TRUE Below is the same code the only difference is the variable names Once you get used to it the first version seems more readable than the second if end_pos wrong error displ else t next_tok char tkn_buf 1 if letter char let TRUE Admittedly using full words for variable names makes the names longer However the increase in readability not reduction of typing is what programming style is all about In larger programs longer variable names can make the code significantly easier to read If you wish to reduce typing even more consider the following version of the same code which is how some programmers actually code C Code written like this is ciphertext It is difficult to read even by people well versed in C There is nothing to be gained but obscurity and programming bugs with code that looks like this if ep erdisp else t nxt c tbuf 1 if let c 1 TRUE Rule 21 Capitalize all constant names Constant names that is identifiers introduced in define statements should be fully capitalized Use complete English wo
10. will probably not get completed Rule 18 Keep the comments up to date Never change a program without reviewing the comments at the same time Read over the comments and make sure that they reflect the current state of the program A program without accurate comments is a sure sign of disaster I consider any program with incorrect or out of date comments as being incorrect itself even if it produces the correct output Never put off changing the comments by thinking that you will go back to revise them after the coding is done Instead you will be busy testing as soon as the coding is done Every program modification should start with a modification to the comments If you are unwilling to modify the comments you should not modify the code itself The comments are a part of the program they must be changed together Rule 19 Document each program file Here is an example of how the beginning of a file should look lexer c PCAT Lexical Analyzer kk Harry Porter 2 1 95 OK to Copy and Distribute Page 14 Modified John Doe 3 15 97 Modified Jane Smith 10 11 98 Kk A lexical analyzer the PCAT programming language See the xx document titled The PCAT Reference Manual for details about the lexical nature of PCAT KK The primary routine provided here is getToken which returns a token each time it is called however other routines may be invoked from external code include
11. your own code then it is without doubt unmaintainable and consequently worthless On the contrary if your programming style leads to a clear program it OK to Copy and Distribute Page 5 will be all the more possible for you to fix it quickly or even to delegate its maintenance to someone lower on the corporate totem pole leaving yourself free to take a long lunches play golf or write new code Don t ignore things don t procrastinate As you are coding or testing you will notice things about your program that you will need to go back to take care of later For example as you are coding you might think Don t forget to test the case where x 0 Or perhaps while you are testing you might think Whoops I messed up this section I did a similar thing in another subroutine I wonder if I messed that up too It is very important not to forget these thoughts Keep a piece of paper next to your computer and make a list of things you need to go back to Write down tests you really ought to try during debugging Write down things about your code you intend to go back and check on Often when you make one change to your code it will require several other related changes Each change must be tested Right at the beginning make a list of all the things that will need to be changed Then as you go through your list you can concentrate on each thing more fully without worrying that you will forget one of the items on the list
12. Harry s Style Guide Helpful Hints for Programming in the C Language Harry H Porter HI Computer Science Department Portland State University October 22 1998 Abstract This paper contains several suggestions about how to write C programs that are more readable and more likely to be bug free This is a C programming style guide documenting a number of coding practices conventions and standards along with justifications of why these recommendations produce better programs Programming style leads to program correctness The most important aspect of a program is whether or not it works correctly A program either works correctly or it does not and when it does not work nothing else really matters A program that does not work correctly is useless The key to creating good programs is to create programs that are readable easy to understand and attractive to the eye If a program is easy to understand then it becomes easier to see how it works If it is easier to read then you can look it over find its bugs and repair it quickly and efficiently If the program is clear and understandable then you can read over it to see whether or not it will work the way it is supposed to Readability is a question of style Adopting a well thought out and consistent style of programming goes a long way toward creating correct and readable programs Anybody can create a working program the great coders produce programs that are als
13. ace you are apt to miss the indentation altogether The tab key usually gives you eight spaces but this is way too much indentation Complex programs quickly run off the right end of the page and wrap around is far more damaging to readability IE eaae 4 not enough space i s left here Four spaces is acceptable but two spaces are adequate and easier to type Using two spaces also has the effect of keeping the code closer together This reduces eye movement and makes the code easier to read OK to Copy and Distribute Page 8 DE os wig eels This is easier to read Rule 4 Limit your lines to 80 characters in length The original IBM punch cards could each store a single line of exactly 80 characters Today different window sizes can accommodate various line lengths If your code is displayed in a window that is too narrow long lines will be wrapped onto a new line This makes code difficult to read To prevent unwanted wrap around I recommend limiting lines to 80 characters in length since that is often the default size for windows displaying text I don t recommend counting characters on each line that is too bothersome but I suggest breaking apart lines that are obviously longer than 80 characters When breaking a long line into two indent the second line a whole bunch to make it obvious that it is a continuation line wrong X atbtctdtet f E gtht ti jgtrk t l m nt otptqt r Ss rig
14. afest way to make sure that the user s manual doesn t get separated or lost and to make sure that it stays up to date Putting the user s manual in the program s block comment also nicely handles the situation where there are several versions of the program floating around Each version performs differently and needs its own user s manual tied to it In many programs it is reasonable to include the user s manual in print statements within the program itself This allows the user to have the user s manual displayed while he is using the program Perhaps the program has a help command that causes the information to be displayed In this case the block comment at the beginning of the program can refer the reader to the section of the file containing those print statements If the file contains pieces of a larger program as in this example the block comment should also include some information on the interface between the code in this file and code in other files Program Preamble and Blank Lines Following the block comment will be often be 1 include directives 2 global data definitions and 3 procedure headers This example has all OK to Copy and Distribute Page 15 three sections each should be separated by a single blank line It is okay to insert additional blank lines to separate large data declarations and the like for clarity but always use a single line at a time Since the first routine will
15. am more difficult to maintain it may be worth it since it may reduce your coding timing dramatically Summary The goal of good coding is to produce software that works correctly and that can be repaired or modified easily With larger programs the fundamental key to this is to create programs that are easy to read both by you and others Following a set of stylistic conventions like the rules described here when you code goes a long way toward achieving the goal of creating good readable software When coding there are many decisions to be made Some decisions are large and complex but many decisions are trivial and mundane like when to insert an extra space character The countless unimportant decisions of formatting your code each distract you a tiny bit from the main task Slowly they tire your mind opening the way to mental fatigue which in turn will detract from the quality of your code and impinge on the logical correctness of your programming By adopting these stylistic conventions you are freeing your mind from the drudge work of coding and allowing it to concentrate fully on the bigger picture namely the much harder tasks of creating high quality complex software systems OK to Copy and Distribute Page 18
16. as the program is written Testing should be done while you are coding the program not after you are done coding You are most familiar with the program while coding it so that is the time to test it You should write a small section of code then you should test that little piece thoroughly Only after convincing yourself it works can you move on to writing the next section of code I call this fine grained testing When coding it is very tempting to continue coding until the entire program is complete instead of stopping to perform thorough testing after completing small pieces of the program This is the devil speaking to you and you must fight his perfidious temptations with all your will You may think it is faster to finish coding a large chunk of program and then go back and do the testing all at once You may even rationalize it by thinking that your program cannot be easily tested before it is all done and that testing will go much faster when performed on the completed program Well this is true testing will be faster but only because it will not be as thorough For example you might think it would be much easier to test the computation section of the program after you finish writing the piece of code that displays the results Unfortunately when you finally get around to testing you will be much more likely to focus your testing on the display code and neglect minor aspects of the computation code You mu
17. be preceded by three blank lines it will be clear where the preamble ends and the subroutine code begins Local Routines It is a great idea to include subroutine headers i e declarations which list parameters but not code for all routines occurring in the file as was done above at the beginning of a file There should be exactly one line for each subroutine and they should occur in the same order as the subroutines appear in the body of the file This section then becomes a handy index to the rest of the file There should be no attempt here to document the subroutines themselves since that will be done in their block comments Standard C practice is to put routine headers in h files which are then included This is also acceptable and both approaches should be used together Generally the h file should list only the routines that form the external interface In the file itself you should list all routines including those that are only called from within the file Global Data Global variable data should be collected and placed at the beginning of the file The understanding of the global data structures is usually critical to understanding the entire program the global data structures should be documented as necessary Often the author of the program will understand the global data structures so thoroughly that he will fail to document them adequately However a lack of understanding of the global data structur
18. de sets them off visually This rule applies to the assignment operator as well x a b c lt 100 amp amp d gt 1000 right x atb c lt 100 amp amp d gt 1000 wrong Rule 12 Do not use the assignment operator in expressions In C the programmer may use the assignment operator in embedded expressions The justifications for allowing this are 1 it makes the language simpler and 2 the resulting code may be more efficient Unfortunately mis typing an equality operator is a common mistake and once made is often difficult to catch Even when coded correctly the operator can be easily mistaken for when reading the code making it easy to overlook an assignment and therefore difficult to understand the code correctly Therefore I avoid using the assignment operator everywhere except in an assignment statement directly OK to Copy and Distribute Page 12 if done atEOF problems wrong done atEOF problems right if done After getting used to this convention every operator in an expression begins to stand out like a red flag which helps to spot errors more easily As to the question of target code efficiency an optimizing compiler will probably generate the same code regardless of how the source code was written so this is not a reasonable concern Rule 13 Use a space between a function name and the following parenthesis In a sta
19. e familiar with the group style it will be easier to read code written by other programmers If their code looks like yours it will be much easier to accept it and to focus on the issue at hand namely its correctness If everyone s code looks different you can easily find yourself favoring your own code and despising their way of doing things When there are no stylistic conventions imposed on you create a style of your own If you are programming in an environment without restrictions find a consistent style and begin using it As time goes by your style may evolve and improve but seek to maintain a consistent style Code is most often read by its original author It is far easier for a program to be modified by the person who wrote it than by another programmer Thus whenever a program must be corrected or altered it is logical for the users to seek out the original author to fix it Nevertheless it always difficult to go back to an old program even if you wrote it yourself and modify it When you write comments it is possible that you will be the only one to ever read them again This is no excuse to alter you programming style or relax your standards In fact it is a good reason to keep them high If your employer confronts you with code you wrote two years ago asking you to correct or change it and you are faced with poorly written code that is difficult to understand the loser will be you If even you can t maintain
20. es makes it almost impossible for anybody else to understand the rest of the program Always be careful to provide accurate and complete descriptions of the global data Rule 20 Spell variable names using English words I recommend creating identifiers that consist of full English words For example tokenBuffer parseReadStatement The first character of each word is capitalized and all other letters are lowercase Begin the variable name with a lowercase and avoid the underscore character I recommend using only valid English words and spelling them correctly since it makes it much easier to remember how an identifier was spelled I recommend avoiding the underscore character in identifiers because it is too easily confused with a minus sign and because it is too visually distracting These rules apply to variable names and subroutine names Variable names should be given names that are nouns like tokenBuffer and whiteSpaceCharacterSet Subroutines should be given names that are actions or commands like getToken and printError Routines that return true or false should be given names that ask a yes no question such that a yes answer corresponds to a true result For example the routine isLetter might used to test a character and return true if it is a letter character Boolean valued variables can be given names that form a statement of fact like gotLetter and atEnd Variables that are only used
21. he condition is false the very first time the loop is encountered and you should also run tests in which the while loop is executed several times With for loops like the following example you should run test cases where initValue is less than MAX where initValue is equal to MAX and where initValue is greater than MAX The first test will check the case when the loop body is executed one or more times the second and third tests will make sure the code works when the loop body is not executed at all OK to Copy and Distribute Page 3 for i initValue i lt MAX i It goes without saying that you must examine the output from your program to make sure it is correct It is never sufficient to just run a program to make sure it doesn t crash You must make sure that the result is correct You must also make sure that there is a connection between the portion of code that you are testing and the output that you are getting It is not sufficient to simply execute every line of code at least once you must also make sure that the output you get indicates that every line of code is working correctly Begin with random testing if necessary The idea of random testing is to sample the space of possible inputs by selecting a variety of test inputs more or less at random The goal is to adequately cover the entire set of possible inputs by choosing a sufficiently large subset of
22. ht X atbtct tdtet f E gtht ti jgtrk l m nt otptqt rh s3 Rule 5 Indent continued lines to reveal their relationships There are a couple of cases where a list of several items on a single line would be clearer if the items in the list were lined up and placed of consecutive lines Don t hesitate to line things up when it helps to show their structure Here are a couple of examples foo x y 23 anotherRoutine a 1 b 2 c 3 sqrt z x w u v if x y z printf Rule 6 Never use the tab character Some software still has problems with the tab character For example the amount of space implied by a tab is not fully agreed upon and what is worse can be changed by different users Always use spaces Your program will then look exactly the way you want You may assume that OK to Copy and Distribute Page 9 your program will be displayed with a fixed sized character font but it will look okay even if it is not Typing all those spaces may seem like extra work but I find that I can hit two spaces about as fast as I can hit the tab key If you are concerned about the additional disk space used by all those spaces instead of the more efficient tab characters take a deep breath and try to have perspective with today s disk capacities this is not a reasonable argument Spend your energy learning to use file compression software and save far more
23. inputs If the program works on randomly selected test inputs the theory is that it will work on all inputs In debugging a program many tests must be run and you must organize all this testing some way One approach is to begin by simply making up tests at random Such randomly selected test data is often useful when you just want to see if any of your code works at all So you can begin with test cases in the middle by randomly selecting the first few test inputs As long as you are finding bugs this way it is perfectly okay to proceed with randomly selected testing This is a good way to get a fair percentage of your code working Sometimes it is necessary to get something working before you can begin serious testing Don t use random testing for fine grained debugging Random testing is never adequate by itself and I don t recommend spending too much time with it Unfortunately the set of possible inputs is generally infinite and furthermore the space of inputs is rarely uniform and continuous All this makes it impossible to select a subset of inputs that accurately represents the set of all possible inputs Instead you are taking stabs in the dark and it is very easy to miss gaping holes in your code However it should be noted that random testing will often turn up subtle bugs that would go undiscovered otherwise especially due to misconceptions about the problem domain itself Therefore really thorough tes
24. nd of testing on it suppose you proceed to work on another piece of the program that uses this subroutine Later you must test to see that the larger program can call the subroutine You must ensure if nothing else that the correct subroutine is invoked Also when you come back to test a piece of code later you may see things that you missed before Your eyes may strangely be opened to new possibilities for the same reason that we often understand our problems more clearly after taking a coffee break or spending a little time diverted with other mental distractions However of all the testing the initial fine grained testing is the most important You can often achieve a correct working program with only fine grained testing but you can rarely achieve a correct program without it Who will read your programs There are several styles of programming appropriate for different programming projects and you must know who your audience is when you write a program The biggest question is whether other people will read your code or whether you can be sure that you alone will read it If you are programming for a company or other organization they should have standards and recommendations about programming style Follow their recommendations even if they seem awkward silly or outright bad The primary motivation for company wide standards is to make the code written by different individuals look as similar as possible Once you ar
25. o clean and attractive to the eye Programs must work correctly Programs must work correctly Always remember that program correctness is absolute either the program does what it is supposed to or it doesn t Or you are so hopelessly confused that you don t even know what it is supposed to do Although some theoretical research has shown that it is often difficult to define correctness precisely or that it is often difficult to prove correctness beyond a shadow of a doubt these results don t negate the fact that a program is either correct or flawed Either a program meets its specifications performing correctly in all cases or the program contains bugs and is flat out wrong Our goal is to always produce correct programs Anything we can do to make that task easier is worth trying OK to Copy and Distribute Page 1 Of course gigantic programs are created by teams of people leaving no single programmer with responsibility and become so complex that bugs become inescapable They get so big that no one can understand what is going on and problems remain buried under vast heaps of confusion Companies employ statistical measures to determine how many bugs are likely to remain undiscovered in the code and they make market decisions about whether it is more profitable to release programs with bugs than to delay the release in order to fix the bugs Large software companies often intentionally release programs with known bugs because
26. on will often need to refer back to the declaration to see what the type of the variable is Placing OK to Copy and Distribute Page 13 declarations in the body of the code tends to hide them This is true even of temporary variables Put all declarations at the beginning of the subroutine For temporary variables use short one character names so they can be easily recognized as being less important than other variables Names like t i and x are recommended Insert a single blank line after the variable declarations and the actual code foo int t totalCount if t ie Don t use int t here totalCount prevCount t Rule 17 Write block comments before coding When you begin to write a subroutine start by typing in the block comment first If you are unable to write the block comment you are not yet ready to begin coding You must have a very clear idea of what a subroutine will do before you code it If you can not articulate it in words then something is very wrong Finish writing the block comment before you code one line of the subroutine This will free you to think only about the code while you are writing it While coding if you discover a problem in the block comment change the comment before going on If you focus on the comments first the code will be easy to write and more likely to be correct If you focus on the code first it will be confused and the comments
27. rds and use the underscore character to separate different words For example define TRUE 1 define FALSE 0 define MAX BUFFER SIZE 100 define MAX NUMBER _OF_ SYMBOLS 200 Rule 22 Don t use all the features you can Many people like to use newly acquired knowledge In general this is good since it helps you become familiar with the new material But if your goal is to write programs that are easy to read and understand then you make things more difficult whenever you incorporate new features If you have just learned some new feature of a programming language using that new feature will make it impossible for a person to understand your program unless he has at least as much knowledge as OK to Copy and Distribute Page 17 you And if he has more knowledge than you it is more likely you will be reading and maintaining his programs It is preferable to adopt a reasonable subset of C and just use features in that subset For one thing you become more familiar with the pieces you are using When you use a new feature that you have just discovered it is more likely you will make an error For another thing when another person is reading your code he will need to adjust to your style of coding If your code is unnecessarily complex it will take longer before he becomes comfortable with your style Rule 23 Avoid using other software These comments also apply to using software packages when writing programs Every time you
28. sistency Within the text of the comment the parameters may be referred to by the names used in the first line of the block comment The text of the comment should be written in complete correct English sentences Complete sentences are much easier to read and understand than fragments Incomplete sentences often leave room for misinterpretation The comment should be of the form This routine does such and such In other words the text takes the voice of telling you the reader what the code below does The comment should not be of the form Do such and such The block comment should mention each argument i e each parameter and explain its relevance to the task being performed If the routine returns a value this should be described in the comment If the subroutine returns a Boolean the comment should be clear about what TRUE means and what FALSE means by saying something like The routine returns true if such and such holds and false otherwise OK to Copy and Distribute Page 7 A block comment should describe what the subroutine does not how it does it It is written mostly for the benefit of whoever is writing the code that will call the routine not the person coding the subroutine itself so the first goal is to clearly specify what the routine does so that it may be used by others The details about the algorithm used within the subroutine are generally not important to the caller so they are not included It is
29. st test small pieces as you write them You must practice fine grained testing Test the boundary conditions OK to Copy and Distribute Page 2 When you begin testing your first tests should test cases in the middle In other words your first tests should confirm that the code works correctly for easy examples and simple inputs to make sure that you have all the main parts in order and can produce outputs All programmers do this level of testing to make sure the program works for the simplest data but many programmers skip the next step of testing which is to test extreme cases You must test the boundary conditions the unusual data sets and the weird inputs much more thoroughly than the middle cases because this is where the subtle bugs will lie hidden What if the user hits enter immediately without entering any data at all What if the array size is zero or the list has length zero What if the value of x is the largest integer representable Tests of this nature are best designed immediately after writing the code because it is then that everything is fresh in your mind The moment immediately after finishing a small block of code is the moment you understand it best if you wait before performing your testing you will slowly begin forgetting some subtleties of your code This is why you must test immediately after writing the code without waiting Execute every line of code A standard rule of thumb
30. stake If braces are always used you can simply insert a statement you don t need to also remember to add a set of braces If braces are used sometimes but OK to Copy and Distribute Page 10 not others then you may occasionally forget to add braces Then you might end up with code like the following which is misleading and probably incorrect In any case you find yourself thinking about braces instead of thinking about the code itself if x y 2 b c d 9 h i a e if Rule 8 Line up all closing braces Each closing brace should be on a line by itself with the exception of the brace in front of the else keyword as discussed below The closing brace should be in the same column as the first character of the line containing the matching opening brace Every statement within the loop or if statement should be indented by exactly two spaces while x lt MAX LIMIT SOS eset if y 0 jee Y Goss Zo arte lt ee7 The closing brace for a subroutine will be the only closing brace appearing in the first column since only the subroutine header line will start in column one Rule 9 Put else on a line by itself Format all if statements as suggested by this example if nextToken t advance else syntaxError t nextToken All then and else clauses should include braces even if there is only one statement
31. tement or expression that invokes a subroutine arguments will be surrounded by parentheses Insert a space before the opening parenthesis Apply this rule even when the argument list is empty x myRoutine a b c otherRoutine d e f compute Rule 14 Insert a single space after every comma This is the convention in printed English text and it is for a reason It makes lists easier to read if the same rule is also followed in programs routineOne a b c right routineTwo a b c tempting but wrong Rule 15 Avoid inserting blank lines Blank lines add to the program length without adding much clarity However there are several places where blank lines should be used 1 Insert 3 blank lines before the block comment for each subroutine 2 Insert a blank line between the variable declarations and the code within a subroutine 3 Ifthe code of a long procedure is logically divided into several sections add a blank line between them Rule 16 Declare variables at the beginning of the subroutine Declare all variables at the beginning of a subroutine Do not include declarations in the middle of the subroutine even for temporary variables A temporary variable is one that is used only within the span of a couple of lines it does not hold a value over long sequences of execution The reason for putting all declarations at the beginning of a subroutine is that when reading code a pers
32. they have judged the cost of correcting those bugs to be greater than the damage those bugs do to the software companies profit statements This dismal state of affairs makes it easy to forget the importance of producing correct code but the ability to write correct code is more important now that ever before Programs with bugs can cause planes to fall out of the sky and passengers to die Programs with bugs can cause medical monitoring systems to malfunction and patients to die Programs with bugs can cause incorrectly designed buildings to collapse and people to be crushed to death Programs must always be correct Test until you discover every single bug The only effective way to discover program bugs is to test your program As you design and code a program you must also test it In general designing good test data is an art which can only be learned through practice A good rule of thumb is to test until you are not finding any more bugs and then test a little longer to make sure there are really no more bugs You must learn to judge your own feelings about whether a program has been tested adequately If there is the slightest doubt in the back of your mind do not stop testing until that doubt is eliminated Do not stop until you are 100 confident that your code will pass whatever tests you might possibly think of in the future Do not stop testing until you are sure there are no more bugs Testing should be done in small pieces
33. ting also requires some random testing A discussion of serious random testing is beyond the scope of this document To begin thorough fine grained testing I recommend that you look at your code line by line as you create your test data Design each test to exercise one and only one section of code Run the test and then verify that the section of code being tested really works Then move on to the next section of code and design a new test For example suppose you are testing a subroutine you just wrote First you begin with a randomly chosen input that causes your program to produce the correct output Start your fine grained testing at the top of the code for the subroutine Design a test to make sure the first line of the subroutine works correctly Suppose the subroutine begins with an if statement design one test that satisfies the condition and a second test that fail the conditions Proceed through the body of the subroutine line by line OK to Copy and Distribute Page 4 For additional thoroughness come back and test later A single episode of testing cannot be considered thorough After your small piece of code is integrated into a larger program it may begin to interact in strange unforeseen ways To be sure that it works in its context you must come back later and test it again You must ensure that it can be used the way it is intended to be used For example after completing a subroutine and doing the initial rou
34. use some strange piece of software you cut the pool of people who can understand and maintain your code Suddenly your code is dependent on lots of other stuff working correctly If you use some strange preprocessor that you picked up off the net for example it may be impossible for other people to understand your code at all They will need to train on this new piece of software which they don t particularly want to do before they are competent to maintain your software Even worse though is what happens when new computers come out or new versions are released Maybe the company that wrote that preprocessor is out of business now your software is dead too Or maybe they came out with a new version of the preprocessor but decided to clean up some of the features or bugs in their old version Unfortunately their change to their software might require you to change your software Don t you have better things to do The moral is to try to avoid relying on other people s software or other software packages as much as reasonably possible The more software your code relies on the sooner it will fail from changes external to itself The more software your code relies on the more time you will have to spend maintaining your old programs just to keep them working Obviously this rule must be applied with wisdom and foresight since using other people s software may dramatically reduce your programming effort Although it may make your progr
Download Pdf Manuals
Related Search