/* FILE: /bham/common/com/packages/poplog/local/teach/proglect9 AUTHOR: Aaron Sloman CREATION DATE: 22 Oct 1996 COURSE: several PURPOSE: Help with programming, e.g. for mini projects LAST MODIFIED: 20 Oct 1998 */ TEACH PROGLECT9 Aaron Sloman Oct 1998 This lecture is intended to be useful when students are beginning to work on their mini-projects. It identifies some common faults in project reports and how to avoid them. Previous lectures are summarised as teach files, with examples which you can run. TEACH * PROGLECT1 TEACH * PROGLECT2 TEACH * PROGLECT3 TEACH * PROGLECT4 TEACH * PROGLECT5 TEACH * PROGLECT6 TEACH * PROGLECT7 TEACH * PROGLECT8 CONTENTS -- Introduction -- File and procedure headers -- Problems found in programming files -- a. Poor file headers -- b. Lack of test examples for procedures -- c. Test examples outside comment brackets -- d. Problems with apostrophes -- e. Inconsistent use of "?" and "^", "??" and "^^" -- f. Poor use of program and documentation libraries -- g. Mixing up foreach and forevery -- h. Undeclared variables -- Problems found in reports -- a. Missing introduction -- b. Missing sample interaction -- c. Explanations too low level and detailed -- d. Missing critical evaluation -- e. No links to literature -- f. Incomplete pathnames for load commands -- Introduction ------------------------------------------------------- There are many little problems that reduce the quality of programming files. Some of these actually make the programming tasks harder for the student. Some are more concerned with presentation to others, e.g. examiners, or other people who wish to use and possibly extend or maintain the programs. It may be useful to look at the checklist used to help with marking of mini_projects. TEACH MSC.PROJECT.CHECKLIST -- File and procedure headers ----------------------------------------- Use ENTER fileheader To set up a header for each file, and remember to update the header as the file develops. The header of this file was created with that command. Remember to change the file path name if you change the directory. When giving file locations, don't just use ~ to indicate your top level directory. For other people that will refer to THEIR top level directory. So if your login name is "xyz" always use ~xyz, e.g. ~xyz/project/startup.p Use ENTER procheader inside a procedure definition, to set up a header for each procedure definition. E.g. Given this definition define search_for(target, list) -> (found, location); 0 -> location; lvars item; for item in list do location + 1 -> location; if item = target then true -> found; return() endif endfor; false -> found; 0 -> location; enddefine; ENTER procheader Will produce the following header, above the procedure definition, for you to complete: /* PROCEDURE: search_for (target, list) -> (found, location) INPUTS : target, list Where : target is a ??? list is a ??? OUTPUTS : found, location Where : found is a ??? location is a ??? USED IN : ??? CREATED : 22 Feb 1998 PURPOSE : ??? TESTS: */ (For details see HELP * VED_PROCHEADER). -- Problems found in programming files -------------------------------- The following comments arise out of my examination of student files produced while working through TEACH RESPOND, TEACH RIVER2 and other things. Not everyone has followed the instructions carefully. Here are points to remember: -- a. Poor file headers Ensure that information at the top of the file is adequate (e.g. if printed). E.g. give the FULL path name of the file, author, what it is about, etc. in a comment at the top of the file, as explained above. The full pathname can start with ~XXXYZ/ if your login name is XXXYZ. -- b. Lack of test examples for procedures Include test examples for your procedures, or have them in a separate file, clearly indicated in the file header and procedure headers. -- c. Test examples outside comment brackets Do not have test examples or "run" instructions at "top-level" in the file. Put them inside comments. Often it is useful to have a file that starts things up by loading other files and then runs the program. If you load up a file of procedure definitions and it includes test commands you will probably have unnecessary problems. Putting the tests inside comments, like this, avoids the problems: /* ;;; test for run_prog run_prog(list1, list2) => */ See TEACH * RIVER2, TEACH * TOWER for examples. -- d. Problems with apostrophes Apostrophes in words like "don't" cause problems: Use [sorry I do not understand] ==> rather than [sorry I don't understand] ==> as the latter won't work. WHY? An apostrophe in Pop-11 is treated as as introducing a string. That's why it is called the "string quote" character, as opposed to the word quote character. Make sure you understand the error message. (Where's the closing string quote?) There are three types of quotes in Pop-11. String quote: ' Word quote: " Character quote: ` A previous lecture explained some of the subtle difference between strings and words in Pop-11, and how words, but not strings, are entered in the Pop-11 dictionary. See also The Pop-11 Primer, and HELP * STRINGS HELP * WORDS If you must print an apostrophe you can use a string, with "\" before the apostrophe, e.g. [sorry I 'don\'t' understand] ==> or even ['sorry I don\'t understand'] ==> or, if you don't need a list, use just a string 'sorry I don\'t understand' => (See HELP * PRINTF for more information on formatted printing.) -- e. Inconsistent use of "?" and "^", "??" and "^^" This is a very common source of problems. Using "?" in a pattern to pick up an element of a list, and then using "^^" to merge the result into another list can cause a "LIST NEEDED" mishap. WHY? Example: if input matches ! [is the ?obj1 ?rel the ?obj2] then .... [No the ^^obj1 is not ^^rel the ^^obj2] ==> will produce an error (LIST NEEDED). Why? The answer is to be consistent: "?obj1" may match ONE word, without making a list containing that word. "^^obj1" assumes that the value of obj1 is a LIST, not a WORD. "^^" means something like "include the list elements". Another problem can arise if you use something like "??xx" in a pattern. Then if the match succeeds, the variable xx will be given as its value a LIST of items whatever matched the pattern. It could be an empty list. It could be a list with exactly one element. It could have many elements. Then if you wish to create another list using xx, e.g. to print out a message or to insert information in the database, then you must think very clearly whether to use "^xx" or "^^xx". The former will insert the whole list as a single element. The latter will insert the elements of the list separately. When you've inserted the new information in a new database item, you have to make sure that subsequent searches use a pattern that is in the right format to find what you have inserted. E.g. use the "??" form to match items inserted in a list using "^^", and use "?" to match an item inserted using "^". If you don't think very clearly about this, then you may insert something in the database and later search for it using the wrong form of pattern. You may then wonder why your program does not work, despite having all the information it needs. See TEACH * ARROW, and HELP * MATCHES -- f. Poor use of program and documentation libraries VED uses several search lists to find information, in particular: popuseslist popautolist vedhelplist vedteachlist vedreflist Each of these is a list of directories in which to search. The first two lists are also used by the "uses" and "lib" commands. Use of the commands is subtly different: uses .... lib .... The latter always compiles compiles the file. The former only compiles the file if the identifier given has not yet been declared. In general uses "uses" not "lib", to prevent unnecessary recompilation. Also remember NOT to put those commands inside procedures. They should be at "top level" i.e. direct commands in a file, before the procedures that require the libraries. See HELP * LIBRARIES REF * LIBRARY for full information .... -- g. Mixing up foreach and forevery What's the difference? foreach ! do endforeach forevery ! do endforevery; Note: both allow the "in list" extension before "do". See TEACH FOREACH, HELP FOREVERY -- h. Undeclared variables Autoloading and warning messages. If you don't declare a variable, and you have not previously used it as a global variable in the current pop-11 session, then the system will look to see if the variable is a name of an autoloadable library, in popautolist. This can involve searching in a lot of different directories, which causes network traffic and unnecessary use of the disks on the file store, and can slow things down a lot, for you and other users. Worse, it can cause a library to be found that you did not want, and it may be compiled automatically without your knowing, causing problems when you run your programs. When you use an undeclared variable, the procedure prwarning is used to print out a warning. This gives you a clue wrwrw => ;;; DECLARING VARIABLE wrwrw ** Those DECLARING VARIABLE messages are an indication that you must fix something. ALWAYS pay attention to those warnings and find the right place to insert declarations. If you use a procedure before it is defined you can insert a global definition at the top of the file. Sometimes inserting one declaration does not solve all the problems because the same variable has been used in another procedure where it should have been declared as local but was not. This will not show up when you recompile your file (in the same session) because the variable has already been declared as global automatically. You can use the command ENTER resetvars to cancel the variables which were automatically declared, with warning messages. Then if you recompile your file and one of the variables is still used without a proper declaration you will get another warning. ENTER resetvars resets the state of the system by removing the automatically declared variables from the Pop-11 dictionary. HELP * VED_RESETVARS -- Problems found in reports ------------------------------------------ -- a. Missing introduction -- b. Missing sample interaction -- c. Explanations too low level and detailed -- d. Missing critical evaluation Including discussion of weakness and possible further developments. -- e. No links to literature -- f. Incomplete pathnames for load commands In appendix giving instructions on how to run the programs, or in the project report if there are references to some existing programs, any load commands should have full pathname, e.g. Not just load river2.p nor load ~/river2.p but, if your user name is "xyz", something like load ~xyz/river2.p WHY? Answer: so that other people (including examiners) can check out your programs, without having to log in as you. ... this file may be extended .... NB See TEACH * REPORTS for information on presenting project reports. --- $poplocal/local/teach/proglect9 --- Copyright University of Birmingham 1998. All rights reserved. ------