Re: Standards/reasonable programming practices

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. 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 and is so much more confusing than UNIX (of any flavour) for me >to give Microsoft any credit for anything). But the real world seems to >have no 2nd thoughts about using "Cut-and-Paste" as a valid programming >method and it leads to inefficient, difficult to maintain code. > Exactly - I once removed > 505 of the code from a system because 5 people worked on it and they all wrote their own version of functions and/or pasted code rahter than creating func