Categorizing lines of code

[Guy Dombrowski]

Gosub

Gösta,

As I am using PBCC Ide, I find the Bookmark function very handy to move among various GOSUB.
CTRL-B to get the list or CTRL-F to search for a comment I used in that section.

[Gösta H. Lovgren-2]

The problem I see with Gosubs from a documentation pov is they are usually offscreen and have to be scrolled to whereas with a Sub or Function, it's usually just a matter of F6 to jump right to them. And Alt F6 to come right back. (at least in JellyFish Pro) (Not so with Macros, though. Have to F4 -pop up the Functios list- and get there that way.) Maybe not such a big deal to others but important to me.

==========================================
"God gave men both a penis and a brain,
but unfortunately not enough blood supply
to run both at the same time."
Robin Williams,
commenting on the Clinton/Lewinsky affair
==========================================

[John Petty]

As per my original post I agree the documentation value, but I think the point being missed is you can do the same level of documentation (single screen if desired) with GOSUBs. The original Sub or Function actually ends with an EXIT SUB or EXIT FUNCTION. The GOSUB routines, specially if small, can then be clearly seperated and documented just like a normal FUNCTION or SUB with two differences, no setup overhead and after all included in the FUNCTION or SUB the compiler requires an END SUB or END FUNCTION line, proper indenting makes that a simple matter. It is a similar concept to using Macros but with a little more flexability and actually better documentation if done properly. As with Macros the executable is larger but the gain is speed.

[Michael Mattias]

125 procedures * 3 calls each.

375 total calls.

Yeah, that's a real time-waster, all right. Gotta be worth at least three-four days of round-the-clock blood, sweat and tears to eliminate it.

Sheesh.

[Guy Dombrowski]

I am in complete agrement with keeping logic sections in one screen if possible.
When I was writing QB45 code, I used the 80 x 50 option to fit more code in the same screen.
Of course, now that I use a twin 24 LCD setup at its maximum 1920 x 1200 resolution, my usable area is 160 x 50 caracters per monitor.
Plenty of space left for detailed comments.

[Joseph Cote]

I tend to use blank lines to seperate the code into logical steps, usually with an associated comment or two. This is pretty much a language independant habit of mine.

I do COBOL and Java for work. I've had a number of other programmers say that they liked working on code that I had written (well, as much as anybody likes maintenance work.) Good comments and consistant style make it easier for everybody.

[Gary Beene]

Knuth,

Like you, I'm especially keen on being able to visually inspect code and work hard to keep procedures to a single screen. So I also use procedures to help out.

It's usually easy to know which routines (graphic animation) need speed, and which don't (setting a check on a menu item) - so I don't usually get caught on that. However, when speed is an issue I should profile more often. It often seems that procedures are called more often than I realize.

One thing I also do is to use fully descriptive variable name and procedure names. "WriteTreeViewDataToFile" is better than "Save". It has the drawback of making code lines longer, but is much easier to understand a day later.

Then, I am split on blank lines. Having them helps group like code together but at the expense of making the code longer. If a procedure is going to be 1+ screens no matter what I do, then I add blank lines readily.

What I often do is put in blank lines during development - then remove them sometime during code checkout. I guess once I get more familiar with the code, the need for blank lines disappears.

[Knuth Konrad]

.
If the average call is only 3, then one would suspect there are some that are only called once or twice so should be inline code, even at 3 or 4 I would be looking at GOSUB and RETURN
John

Nope, never.

OK, more serious: Maintenance and reuse are the two main goals I'm after with my coding. Some rules I try to follow, when I need to decide to put some code into its own procedure:

- Procedures should spawn over 2-3 screen pages maximum. Everything above is too hard to follow for me. Often this is caused by a lot of code lines in conditional branches. So instead of ...

If <something> Then

   <Lots ...>
   < ... of ...>
   < ... code>

Else

   <Lots ...>
   < ... of ...>
   < ... code>

End If

... I peel out the inline parts of the If statement and transfer it to a procedure ...

If <something> Then

   Call MyProcIfTrue()

Else

   Call MyProcIfFalse()

End If

- Can I make that part of my code generic and perhaps reusable somewhere else?
So, at this point in my current application I need to generate a backup of a file. Fine, nothing earth shaking here. But I could do it either tailored to that very application I'm at right now, for example this app creates backups of \Interface\Data\*.txt files to \Interface\Backup\*.bak. But who knows, in future projects I may need such a routine for <source folder> and <file spec> to <destination folder> and <different file spec>.
The task itself seems generic enough, creating a (self-contained) procedure with source, destination and file spec passed as parameters isn't that much more work. And even if I call that procedure only once from my current project, I've just created a new tool in my library.

- (Short) procedures with meaningful names help read (even for non-programmers) and debug code.
Given something like ...

Function CreateInvoice(ByVal CustomerNumber As Long, ByVal Orders As OrderList, ByVal EmailInvoice As Long) As Long

Local Address As CustomerAddress
Local InvoiceNumber As Long
Local EmailText As String

If IsValidAddress(Address) = %YES Then

   InvoiceNumber = InvoiceCreateNew()
   Call InvoiceAddHeader(Address)
   Call InvoiceAddOrder(Orders)
   Call InvoiceCalculatAmount()

   If EmailInvoice = %YES Then

      EmailText = CreateEmailFromInvoice(InvoiceNumber)
      Call SendEmail(EmailText)

   End If

   CreateInvoice = %INVOICE_SUCCESS

Else

   CreateInvoice = %INVOICE_INVALID_ADDRESS

End If

Without the need to get into "dirty details", you could pass this procedure almost without any explanation to your customer and have him review the workflow.

Bottom line: For me, "clear code" - even at the risk of calling a certain procedure only once - outweighs speed most of the time (if not always).

And when we're talking about speed these days, we're most of the time talking about milliseconds - something the user most likely will never notice.

[Michael Mattias]

Z=  Myfunction (param)

... is a call to another procedure.

So is

   subname param, param

Not sure how you should count....

  Z=   FunctionOne(param) + FunctionTwo(otherparam)

.. because that's a twofer... one line of code calling two other procedures.

MCM

[Gary Beene]

Hi John,

No umbrage taken! Your response was exactly the kind of comment I was interested in - comparing what you do with what I've done.

It did seem like a lot of procedures to me as well.

One thing that I noticed that raised the count is that I try not to minimize code inside the Callback functions - relying on sub/functions to simplify the visual inspection of the Callback code, as well as allowing me to call the code from multiple places. So for every menu item and message of interest, there's often (though not always) a procedure for it - perhaps at least half the time.

As far a speed goes, there are generally no more than 3-5 procedures used in any one task. At least with this app, results mostly appear as soon as soon as I press the button.

The only serious need for speed in this case is with a couple of graphics routines (a mosaic stereogram animation and a falling sand simulation). With those, each has an initialization routine, and then a single execution procedure.

[John Petty]

Gary
Interesting study, so I hope you will take my comments in the posative meaning which they are meant. I am an old speed freak so to see 125 subs/functions only called on an average of 3 times would seem to be a major speed problem. Of course if they are of a substantial size the the overhead of the call will be minor.
Of course there are other good reasons to isolate sections of code in subs or funtions, that is what COM is all about, documentation and reusabilty as well as the auguments about globals.
If the average call is only 3, then one would suspect there are some that are only called once or twice so should be inline code, even at 3 or 4 I would be looking at GOSUB and RETURN
John

[Gary Beene]

Hi Michael, and thanks for the response.

Well, I did note that Sub/Function calls were 3:1 over the lines of declaration.

I'm not sure what all you meant to include in "calls to other procedures" - an example please?

[Michael Mattias]

Since you are in this deep and already had some counts, I'm surprised you did not separately track "calls to other procedures" in your " source code line type" breakdown.

You have "Sub/Function declarations and calling of same" but I don't know why you'd lump these together... declares are compiler directives generating no executable code, but calls actually do something.

[Gary Beene]

I was interested in analyzing the code in my first larger PowerBASIC app (about 3000 lines of code), to see what kind of code I used.

Here's the approximate results:

1000 Looping/conditional flow (select, if, do, ...)
750 All other - basically raw code with lots of assignments
500 Control/Dialog or Control Specific (imagelist, treeview, ...)
300 Sub/Function declarations and calling of same
250 Menu definitions, including context menus, plus setting state
200 Dim/ReDim/Global/Local

There were also about 350 comments, either as separate lines or at the end of lines of code.

And there were about 125 subroutines/functions called an average of about 3 times each. This doesn't include callback code that responds to messages.

Has anyone else done a summary of code from one of their apps? I'd guess that the bigger the app, the more common the results would be, regardless of the type of app involved - whereas smaller apps could be much different.

For that matter, there might be some analysis of this type on the web. I'll go take a look.