Re: Standards/reasonable programming practices

David Williams <djw@smooth1.demon.co.uk> wrote: : # 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 I agree to a large extent with what David have written. He is good. (I snipped other parts only to not make this too huge.) I would however rewrite his example function a little as follows: I like self documentation as far as possible through good names. The function name should essentially say what each function does. That is often enough for simple functions. More complex functions must of course be documented better! I use variablenames with p_ for parameters to functions, l_ for local variables, g_ for globals, m_ for modul level. Where the variables are defined and allways doucmented is the key to readable code. One can easily find the definition *and* the documentation. Then I use extra modifiers for record and array type variables as lr_ for a local record, ma_ for a module level array and so on. Further type information only confuses matters to me in 4GL (this isn't C where such type information *may* be more interesting). For simple functions I also document input and output variables only where they are defined. They *have* to be documented there in all cases. Extra documentation before the function often results in confusion. For more complex functions extra documentation *may* be needed. I do however often write a tiny "essay" on what the function is supposed to do, how, why and when and how to use it (or some of these things as required). I don't think this function requires more documentation than the following: funtion person_job_title_get(p_person_id) define p_person_id like person.person_id, # Primary key of person l_job_title like job.job_title, # The title to return l_retstatus integer # Return: # 0 = OK # NOTFOUND = no # job_title found # Otherwise Informix db # error code. and further as written by David. Some additional thoughts: 1. Spesifications of how the code is going to be written that is crated before you start coding is going to be thrown in the garbage dump as soon as the first lines of code are written. Anything valuable from it is included in the code itself. (This doesn't include documentation at a higher level of what the system is going to do, but even that should be put in with the code or possibly the database definition as far as possible. That's where it may be read.) 2. Pseudo code is key to getting anything to work. It must be written at exactly the right level which requires a lot of experience. You do it wrong a lot of times until you finally gets it right. The initial spesifications (before coding is started) should contain some high level pseudo code. It should give you the key overview of how this part of the system is planned to end up as a complete part. The pseudo code becomes the documentation and is updated as the program is modified over the years. That is easy because it's actually right there inside the code. 3. Programs must be written from the inside out. By that I mean I write a small inner part of the program and gets that to work. It doesn't do anything usefull yet, but it is the inner part of the program as it's going to be in the final version. To get this to work it's sometimes necessary to write small dummies for functions and some other parts of the program not yet written that gets dumped later. That's ok, but must be limited as much as possible. Then you continue by adding another small part to your code and actually run it again. Each part must be so small you can step through it in your mind and be sure it does exactly what you intend it to do. When you continue this way in the end you have a working program where every part is validated. 4. Never ever be afraid of throwing away code you have worked hard on. You have to throw away a certain amount of code (sometimes large amounts) as you can't expect to get everything right the first time you do it. 5. Don't expect to test out defects in your code. It can't be done. Fire your testers (or make them into developers) if you are unfortunate enough to have them. Make your developers responsible for their code from end to end. Developers who don't talk to customers and have to fix the code based on their problems aren't worth much. The developers shouldn't be the support department of course (unless you are a very small company), but they should talk to customers when defects in the code are found. At least sometimes they should also go to customer sites and install the code. To be able to do any design work they have to talk a *lot* to customers anyway. 6. The developers should do as much of the initial design as their ability allows, and it should be more and more over time as they gain experience and knowledge. Noone should design anything without doing a significant amount of coding themselves. That's key to a sucessfull end result. Anyone who want to do design, but don't like, actually love, to code must be fired. Important: The above *does not work* if you employ anything but top level developers. But the others aren't worth emploing anyway. A god programmer is worth 5 to 10 average ones, and is allways worth his wage. Personally I have for the last 15 years allways programmed on the production machine of one of my customers. I have hardly ever had a test database. First time runs of my programs has been done directly on the live data. When you don't earn too much during the build up of a major application and the customer don't want to invest any more you don't have much of a choice. It has however proven very successfull. I have over a five year periode done everything from initial design to documentation, database design, coding, implementation and teaching users at the rate of over 150 lines of essentially bug free 4GL code a day. (Over 300.000 lines of code with very little copy and paste in this periode.) To not have a test database is harder when you employ more programmers. When you do this you should have one for the kind of testing you do