Understood that this thread always addresses non-programmers, non-professionals...
Elsewhere, I mentioned Warnier (for details, just search for "warnier" either in this forum or in outlinersoftware.com) who, in the Seventies, did something revolutionary for mainframe programming, which at the time was done more or less in spaghetti-code style which made stay code reusability an unknown concept, and even hampered code adjustments and code maintenance to the point of unbearability voire impossibility.
Hence his (very mainframes-and-their-then-typical-output-centred,) very strict (graphically, horizontal) tree structure for process/logical flow. Up until some time ago, there even had been (left) one piece of sw to do it on screen, "b-liner 6" (well, there had never been versions 2 to 5 at least, b-liner.com), for 90$, but when I today wanted to check the current price, I got a "Currently Not Available" instead. Well, it was buggy (and development had been stalled a long time before), but it was graphically very pleasant...
Now, even quickly in the Seventies, programming became much more sophisticated, than the Warnier paradigm reasonably could handle: As indicated above, there are several such flows that in an elaborate application will not make their voyage together, and at the very least, you'll get logic flow, and information flow that differ, hence the need, in non-professional coding environments, to do some heavy manual work here, like extensive, manually-maintained lists for triggers, triggered elements (in, out), variables (ditto: "gets var1 from system, updated by trigger routine xyz", etc., and "updates var2 for routine abc, updates var3 which is then possibly checked by routines c and d", etc., etc.).
Now, manual maintenance of such lists is a lot of (error-prone) work, but you can at least simplify this by either using some editor whose search function will show results in a hit table (and which offers code folding, of course), or, much much better, to do your programming/scripting within an outliner which has got such a hit table for search results, too (and where the hit table will indicate the name of the item = routine of the occurence); fortunately, there are some such outliners, from which RightNote stands out because even its FREE version offers this feature, and allows for rtf formatting of text, of which you should make very ample use at least during the construction of your code body, so for people who ain't (yet) into outliners for almost all their work, will be able to start programming/scripting in this free outliner, independently of their possible switching to some outliner for general work later on.
Also, you could do you manual logic and info flow checks on paper, with print-outs and colored pencils, either/or (even) for the original data, or (and especially) for those hit lists (many programs will not allow for exporting/printing of their search hit lists: Just make a screenshot then, and work, with colored pencils, on the multiple screenshot printouts).
Of course, before doing this "macro comparison", i.e. inter-routine (i.e. "are my indications correct, checking alleged sources and targets?"), you'll have to do your "micro comparison", i.e. intra-routine: (full) routine vs. your manually-created "header" lists there: Here, you will work with printouts and colored pencils, preferably, but if you insist on using a hit table, instead, even here, you can do it in every outliner offering "search..." (with hit table, to begin with, naturally) "...just in selected item and its children": For such a setup, you simply divide your item into your header, and then the real code, and in the tree it would be:
; H some routine
; C some routine
; H next routine
; C next routine
H meaning "header", and "C" meaning "code", or whatever you choose for differentiating them:
Then, you select ; H some routine, you search (e.g. for variables, but also for GOSUBs, etc.), and voilà, you'll get your comparison between your initialisations, etc., and your real use of things.
It goes without saying that in programming languages where declaration/initialisation of variables is mandatory, and where there is a clear distinction between local, and then global variables (some ace programmers of today will even tell you that global variables were to be avoided, but that's a whole other story/world (so don't have you fooled)...), both comparisons, intra and inter, are greatly facilitated, but even there, DO THOSE COMPARISONS, as thoroughly as is needed, i.e. down to the last detail (or buy some really professional coding environment, but unfortunately I don't know any that lets me work in such an outlined structure, and does all the above-described tasks for me upon request, so external input from fellow posters would be more than welcome here, and yes, it's understood such sw would be in the 4-digit range).
As you see, this is quite overwhelming a task (but in a good outliner, it's doable at least, whilst in b-liner, e.g., technically it's doable, too, but accessing all those elements that will have to be compared would be a strenuous nightmare (and yes, there are people who get killed in their sleep, precisely by their nightmares!), so most of you will try to avoid it: DO NOT!
AND HAVE PATIENCE IN WRITING. What does that mean? Do not do multiple pieces of tiny code, then being eager to see if it works, but try to build up the architecture of all those interlocking elements, i.e. build some tree sctructure, and do lots of pseudo-code, intervowen with real code wherever real code is at your fingertips, i.e. where you both know how to write it, and can write it down quite quickly, but perhaps leaving out the necessary variables and such...
But whenever you write such "primal code" (i.e. some chaos mixture of pseudocode and real code and, especially, as much of (just provisional!) notes as you'll possibly need later on in order to "complete" your code), whenever it occurs to you that your "code" is not complete "here" yet, do a note what's missing, what to consider, too, what might be included, whatever:
BE AS COMPLETE AS POSSIBLE in your considerations, in your coding. I.e. refrain from following what "they" say, DON'T be concise, but "put it all in": Take those novelists as your example who write 1500 pages or more, before condensing it all into those 350 pages that then, if they are very lucky (or have established their renown already) will become the bestseller you (or your wife) will possibly rave about.
In other words, THINK YOUR architecture/code, in writing it! (But if you try that in an editor, instead of an outliner, you'll probably get lost, or your editor should have really good outlining functionality!) I.e. do some simili-Warnier construct, but vertically instead of horizontally, and with immediate access to both any "code pieces and other explanations to yourself", within the right pane... and without considering the very first node in your tree as the logical source of any tree you might create downwards (and, of course, without cutting your code into TOO many code parts: as said above, whatever code is less than one printout page, even if it's a (but please: cohesive!) logical structure: no need to artificially cut it up into a dozen or so Warnier elements.
Also, and especially in light of the above - big header structures in "comment" format, but so important in order for your being sure every "flow" in your application will be correct (and yes, I should have said it above, I say it know: All that intra/micro comparing code vs. comments, and then inter/macro, header comments vs. header comments elsewhere, will INCREDIBLY minimize your debug time (not speaking of your children some day maintaining papa's code!) -,
there is no need to artificially cut up code into subroutines (e.g. in ahk: GOSUB, nameofsubroutine), together with "endless" header comments there again, when you don't have to possibly access that code from elsewhere (but you should ask yourself if that wasn't an alternative in order to further optimise your application's functionality, among other considerations!):
Instead of cutting code "too big for one page" into several routines, cut it up in several, "simili-self-contained" pages, e.g. within your tree:
; routine (header including comments)
; if abc (code belonging to the if's in the next item (! why not?!) but then with some 10 or 30 lines of its own
; if d (further on in that "broken-up-between-pages" if structure)
; if a (why not? even a sub-structure here!:)
; else (and the code for the else branch)
; if ... (= end of above if structure, with perhaps 3 or 5 more)
; and some more
; here only, some other routine
So, sometimes, you'll get "real big packages", and which are quite homogeneous in such, not in structure, but in what they are deemed to "be" (i.e. not even necessarily re their elements' respective outcome/output), but without these "output" elements then being "accessed from the outside", or in other words, you'll get code structures that are, in some way, quite "final".
In such instances, it would really be quite ridiculous to artificially observe some "one page, one routine" structure, but you'll be well advised to let flow that routine over 3, 5 or 10 pages sometimes, and without endlessly and partly (! or you create inconsistencies if independent routines!) replicating header structures, at the condition of course that within such a several-pages code structure, you'll be able to cut your code into logically clearly distinct parts (but even with "continuation sections, as in the outer if structure in the example above): Whatever is visually easily understandable is perfectly acceptable as code structure, as long as it is "self-contained" (no access from the outside).
So, please take this part of my post as a correction of my post above: I write "from memory" here, and in my post above, the observation of the "one page one routine" rule made me ignore my own experience of those, perfectly acceptable (and perfectly "maintainable"), (sometimes even much) more extensive routines: Atomize, but wherever it makes sense, not where it doesn't!
To resume what I've said above, have patience, i.e. let grow your new code (be it several routines, be it one big routine) for days (and more, if you just work on it 2 hours a day), without trying to run your code or parts of it, and if you have got several locations where you expect the same or similar difficulties, just say so in your comments, but in the meanwhile, "fill up" and complete your whole structure, as best as you can: Write 5, 10 or 15 pages of code, trying to "oversee", to hold in scope, the "big picture", and iteratively switch forth and back between construction questions and details within parts of the construction.
This way, your construction will grow up to the point of being "acceptable" (i.e. further optimization, or even later rearrangements will perhaps be necessary AFTER "trying out", "running for tries", i.e. (starting) debugging, but most rearrangements will even be done here, before "starting to try"), and at the same time, every part in it will grow to the point of where it will BECOME reasonable to THEN complete the real code everywhere, i.e. replace pseudocode and comments whenever you feel it will be quite "final", i.e. writing too many lines of real code too early in this process will mean AND many lines of code for the bin, AND annoying retardation of structure...
whilst any try to perfect structure, without code, will (except for some ace programmers perhaps) result in more or less faulty structure, since it's also in writing code (and pseudocode, but quite near to real code) that it will occur to you that alternative structuring will get "easier/better/more accessible/or even just:possible vs. impossible!" code, i.e. in many instances, (alternative ways of) code structure and (alternative ways of) code detail are so interdependant that you should find your way of doing both, architecture AND start-of-finition, concurrently.
(Instruments like UML try to facilitate this, but especially for UML (and for which there are several free sw offerings), I personally think that the graphic represention in most of its instruments is the worst, most non-intuitive and most non-immediately-catchy(=comprehensible) I ever encountered anywhere - UML is a nightmare imo, and then, it's not even smart enough when combining different overlaying structures, instead of doing them in (much too) separate views (it's just that (paid) UML sw obviously comes with some very welcome automation (see above))...
Hence: Start from tree, or from several trees one below the other(s).
Fill the content fields with some content (comments of which the bigger part will be deleted in your work).
Create new branches / subbranches (name the routines you will create, add new comments).
Do some code here and there, enough to discover structure.
Amply use rtf formatting for everything you do (= one of the BIG advantages over editors!).
Create new branches, etc. whenever you deem "necessary for perfect clarity" to separate (future) code from other code parts.
Rearrange branches / subbranches / code pieces within content fields.
Fill up the content fields as much as necessary in order to get it "complete".
Then: Revise your pages, one by one, checking if CODE is complete there (and if NOW you will have formatted any comment there that will (for the time being at least) stay there, as comment) (and replace pseudocode in several such pages in one row if up to then you had done similar code parts in pseudocode/comments instead of real code (e.g. because it's "obscure"/difficult commands you first had to look up).
Then: Do the above comparison work: headers vs. bodies, then headers vs. headers.
Check logical flow.
Check info flow. Check variable names, and variable contents. Check (AHK!) if here and there, you will have mixed up name and content.
THEN try to compile, even if it's a month later. NO! First (ok, you could have done this above already, but don't do it before your code is "semi-final"), put multiple msgbox, 1/2/3: variablename _%variablename%_`n_%anothervariablename%_ lines into your code (accent grave plus n is new line, _ is for being sure to exclude possible leading/trailing spaces, and since you will see the variable names in your printouts, you can leave out them in your message boxes:
msbox, 54 _%var1%_`n_%var2%_
, etc.), multiple such msgboxes I said, and often with braces and a second, return line, and most often out-commenting the real line, the one to be executed. Print all your pages out then, and check the proceeds, in the next step, one message box one by one: Is the variable in msgbox 28 the variable you will have expected there? (If you don't number the message boxes, as described above, you will not know WHERE in your code you will have got the right or wrong variable values.
Since NOW try to compile, and trial, perhaps only for the main parts of it (cf. your replacing (!) executive "subs" by "just showing the respective variable values" above). On paper, check the variable values, with "ok"s (or what you get). Then, revise the code, then "open up" such "subs" (whenever the higher structures give correct msgboxvalues), in order to check smooth running of the "inner parts", too: Step by step, replace msgboxes (which could also contain passages like "In reality, it would trigger sub xyz here.", but just look at your page instead!) by real code execution, up to obtaining perfect code (or seeing where you better rearrange your construct).
Or in other words, iterative coding is not a synonym for "coding by chaos". But Warnier structures et al. had been too stringent, and that harms creativity even for building up the "macro" structure, i.e. the repartition of intermediate, not only lower branches. And, you know this already, but just for the beauty of the pic: Build some wood, not just one tree. ;-)
Start with RightNote FREE if you don't have same (good) outliner anyway.
Don't say "But my outliner doesn't do code completion (for ahk or whatever), whilst my editor does!" whenever your outliner comes with the above-described core functionality for programming/scripting and your editor does not.
Ok, this wasn't only "How to write code as I see it", but also "how to debug (and considering that the real difficulty in coding is not logic structure in its stricted sense of the term, but info flow, i.e. the process flow created by info in variables and such)" and even "how to use the original language to do the prototype", but again, I'm addressing fellow non-professionals here, so I seriously think my advice could be helpful to some of them.
As for a certain Mr. Orr, well, you wouldn't name a train after people who just jump onto it when it has started to run, even when it then feeds them quite well a life long, would you?
And here's the inevitable "and I also would like to share this..." part; please allow, for once, to share the very best piece of comedy ever produced after Groucho Marx, but which is unfortunately available in German only, and worse, in a German intonation that would ask for more-or-less-native German speakers in order to "get it all"; I would not have dared mention it, had the quality of that tour de force not been world-class. And then, it also comprises some outstanding sax performances by Simone Sonnenschein ( simonesonnenschein.de ) which are perfectly accessible to non-perfect-German speakers, too, and of which the one right after the break, "Free Jazz", is without any doubt the most hilarious piece of (so good, en plus !) music in the whole world of music, since ancient history.
Well, this rave performance is from 1999, is called "Hip Hop für Angestellte", and is by and with Piet Klocke:
http://www.youtube.com/watch?v=ekvxHsVEPq0Enjoy (the music at least: listen at very low level (and without picture: Without understanding his speech, you'd mistake Mr. Klocke for a dangerous lunatic!), then rise it whenever the sax plays, and remember, that grandiose lady starts piano-piano (= in a very subdued mood), so early asking yourself, "so what?!" would be a BIG mistake. (And bear in mind that her singing at the end is for comic effect, not to compete with Frederica von Stade!)) ;-)