07-26-2024, 01:34 AM
(This post was last modified: 07-26-2024, 01:37 AM by PhilOfPerth.)
As someone close to the bottom of the “programming chain”, I just want to make a few comments on what makes programmes understandable, at least for me. I know some members won’t agree with some of these things, and some seem pretty obvious, but I find they help me to understand someone else’s programming.
Comments: A few words at the end of, or before, a line that introduces new elements or features can be a great help, not only to other readers, but to the author when editing or reviewing later. They don’t greatly increase the programme size, and are not included in the compiled programme, so why not use them?.
Variable Names: These should give an indication of what they represent. An abbreviated form, maybe with vowels removed, is often ok, but a full word is even better: “TopScore” is clearer than “TpScr”, and won’t be confused with say a “TopOfScreen”, but either one is better than “scmx%”. Some names will necessarily be a bit obscure, especially with advanced trig or system items, so may need a comment to give some indication of their purpose, when first introduced.
Labels: When a new section of a unit starts – whether in the Main or a Sub or Function – it helps if that section is spaced out, and given a meaningful label, telling the reader what the section does, e.g. “CheckBoundary:”. Although spaces are not allowed in labels, CapitalLetters or Under_Scores can be used instead.
Subs and Functions: should have a meaningful name that describes their purpose, and if necessary a comment explaining this.
Programme Names: These should give enough information to tell readers what they can expect to find in the programme. An Introductory page or paragraph that can be seen on opening can also be useful.
Many writers do these things as a matter of course, but occasionally they become so involved in making the programme smaller, or work or run faster, that these are overlooked, leaving readers like me mystified about the purpose of that section, or of the whole programme !
Comments: A few words at the end of, or before, a line that introduces new elements or features can be a great help, not only to other readers, but to the author when editing or reviewing later. They don’t greatly increase the programme size, and are not included in the compiled programme, so why not use them?.
Variable Names: These should give an indication of what they represent. An abbreviated form, maybe with vowels removed, is often ok, but a full word is even better: “TopScore” is clearer than “TpScr”, and won’t be confused with say a “TopOfScreen”, but either one is better than “scmx%”. Some names will necessarily be a bit obscure, especially with advanced trig or system items, so may need a comment to give some indication of their purpose, when first introduced.
Labels: When a new section of a unit starts – whether in the Main or a Sub or Function – it helps if that section is spaced out, and given a meaningful label, telling the reader what the section does, e.g. “CheckBoundary:”. Although spaces are not allowed in labels, CapitalLetters or Under_Scores can be used instead.
Subs and Functions: should have a meaningful name that describes their purpose, and if necessary a comment explaining this.
Programme Names: These should give enough information to tell readers what they can expect to find in the programme. An Introductory page or paragraph that can be seen on opening can also be useful.
Many writers do these things as a matter of course, but occasionally they become so involved in making the programme smaller, or work or run faster, that these are overlooked, leaving readers like me mystified about the purpose of that section, or of the whole programme !
Of all the places on Earth, and all the planets in the Universe, I'd rather live here (Perth, Western Australia.) 
Please visit my Website at: http://oldendayskids.blogspot.com/
Please visit my Website at: http://oldendayskids.blogspot.com/
