Re: Standards/reasonable programming practices

David Williams wrote: Excellent reply, you said it much better than I did or could! > > In article <24ADAAF30F7A9421.EE3E6B8CC1F497D5.1BC89A02A7853FDC@library- > proxy.airnews.net>, STOPSPAM <danwright@bigfoot.com> writes > >I am deliberately posting this here instead of to a programming or > >standards NG in hopes that some of my co-workers may by chance see this > >and understand where I'm coming from when I get on my soap-box about > >standards, in particular documentation! > > > Good! > > >I was told in a response to a message that I posted on our intranet news > >server that it is an "informal standard" to document return values, > >files generated, (basically all input/output) of all programs at the top > >of the program. (I didn't even bother to mention that I strongly > >believe this should be done for every single function, no matter how > >simple.) > > > >When I spend several hours just figuring out what the purpose of a > >simple function with references to a host of mod-scope variables and > >database fields, and then briefly document that in 10-or-so lines, I > >feel that because others have failed to comment, I wasted (and no doubt > >countless others have wasted) hours of billable time, just to make a 1-2 > >line modification or bug-fix. > > > I have this all the time or else see comment like > > While (still_processing = TRUE) # While still processing > > Like they really help! > > >Well, it's hard enough to get people to pay attention to formal > >standards, let alone "informal standards" (whatever that is...I would > I agree. > > >think it is an informal standard to not program bugs, but then again > >nobody's perfect, and I've made enough bugs to overwhelm the mosquito > >population of the Mississipi basin [yes, I hope I have exagerrated on > >that point]. > > > >This feeling dates back to the time before I had any formal education, > >which consistently reiterated that you comment, comment, comment, up to > >the point where one grad-level prof. instructed us that we should "not > >be ashamed to show this code to our mothers" (meaning it should be neat > >and well-kempt, as well as functional). > > > My graduate professor said you should be able to still down with a > mug of coffee and read it like a good book..seriously! > > >It was grilled into me that every function should contain 4 basic > >comments even before any code is written (Inputs (arguments passed), > >Outputs (return values, files generated), Side Effects (mod-scope > >variables modified), and a description of the purpose of the function.) > > This is really excessive and nobody comments sideeffect of module > variables - often the side effects depend upon what is passed in. > > I prefer comments of each module level variable as to what it > contains, assignments to it should then be obvious as to what > they are doing. Also each functions should contain > > good comments as to > > a) inputs - not variable names (I can get that from the code) > but what they mean + what values are valid ones. E.g. > for an integer is -999999999 valid? is -1, 0, 1, NULL? > Should it be always > 0? Something about What is valid. > Well, I didn't mean just to tell me what is passed in, but what values are valid and what they mean, as you said. > > b) return values > I can get the types from the code, what do they mean > are? any special values returned e.g. -1 = error. > > Unless errors cannot occur e.g. it is a function which > does a calculation and will stop the program with an > error message if it fails i.e. WHENEVER ERROR CALL > FN_fatal_message then the first return value should be > an integer status code with 0 = OK, anything else means > an error occured. Use -1,-2,-3...for internal errors. > > Validation functions can skip this if they return > TRUE/FALSE as an error can just return FALSE. > > c) Create a code outline in pesudo code (remember that?) > This is both the algorithm + comments for the final > code:- E.g. to validate a xx_code (function header > in 4GL style) > > # Function: gets_per_job_title > # > # Input Paramaters: person_id - Unique id for the person > # > # Usage: Get the persons main job > # > # Output Parameters: return_status > # 0 = OK > # NOTFOUND = No job > # otherwise Informix error status > # > # job_title - the title > FUNCTION validate_person(person_id) > DEFINE person_id LIKE person.person_id > DEFINE job_title LIKE job.job_title > > DEFINE ret_status INTEGER > > # Use person id to select from person table > > # if not found report error > # else > # do nothing > # end if > > RETURN ret_status,job_title > END FUNCTION > > > Note > > a: Input parameters and types are clearly defined as are the > output parameters and types. i.e. the functions interface > to external code. This means code can be written to call this > function even though it does not yet exist. > > b: For input/output parameters valid values have be defined > (person_id must be unique)!. By defining input/output parameters > like database columns the valid values are automatically defined > as are where the variables ome from in the database. i.e. > how to mathe variables to database columns. This means that > validation information + 'real world' meaning only has to > be defined in the descruiption of the database structure and > can be infered within the pseudo code. > > c: Also a status code is returned and the standard name for this > variable (ret_status) has been used. Values for the status code > are defined (with the convention of 0 mean OK, no errors). > > c: Pesudo code has been used to define the algorithm used. > > d: The "else do nothing" part shows that all cases have been > considered (and should be left in the final code to show this) > > >These should be written before any coding is even attempted (think back > Agreed as above. > > >Further reading on good programming practice, netted me the following > >heuristic "we get worried if a function spans more than 2 pages"...this > > Agreed - functions should be used to split the code down into > managable, clearly defined chunks. Or use methods in object > orientated code. Use private methods to hide methods internal to the > class. Like using module level variables to hide data local to > the class/module. > > >is not a direct quote, and my distaste for the company which published > >this book prevents me from revealing it's source (Windows crashes way > >too much