Tidy enhancement suggestion

[Zaxon]

I have a suggestion for JdeB's Tidy program, which I think is great program.

Tidy's raison d'être is to clean up code to become neater, and more visually appealing. It does this task well.

Like any good programmer, I make highly modularized code on any project of size. This means the code is broken down into many small independent functions. In practise, it means dozens of small functions stuck in wherever your cursor happens to be at the time, and for a large project, you tend not to order your functions very well, and they quickly become hard to find again.

The suggested enhancement to Tidy would be to reorder the Func...EndFunc's into a more logical fashion.

For instance:

* functions which are closely related should be grouped together. Closely related could mean:

1) functions which call each other

2) functions which have a similar naming structure: close_mywindow, open_mywindow, repaint_mywindow

etc

I believe that this would be a good fit for Tidy, since it is tidying up function ordering, producing more aesthetic, more easily readable code.

Function reordering would of course be optional, so your functions stay in the order you write them if you so choose.

Some thought would have to be put into what is considered a logical way of grouping functions. My two suggestions above would be a good starting point.

[Jos]

The suggested enhancement to Tidy would be to reorder the Func...EndFunc's into a more logical fashion.

For instance:

* functions which are closely related should be grouped together.  Closely related could mean:

  1) functions which call each other

  2) functions which have a similar naming structure: close_mywindow, open_mywindow, repaint_mywindow

  etc

<{POST_SNAPBACK}>

mmhhh ... Sounds like an interesting option.

1. not sure what here the logic would need to be... I am open for suggestions...

2. sounds possible to have Tidy order the Func...EndFunc in an Alphabetical order at the end of the main code.....

[SlimShady]

All the UDFs should definitely be at the bottom.

I'm not sure if it does now, but it should.

[Zaxon]

mmhhh  ... Sounds like an interesting option.

1. not sure what here the logic would need to be... I am open for suggestions...

2. sounds possible to have Tidy order the Func...EndFunc in an Alphabetical order at the end of the main code.....

<{POST_SNAPBACK}>

That's one option. In the case of functions like: open_something, close_something that would spread out those functions rather than grouping them together.

The concept is that functions which are related to each other should be placed together.

The three ideas that popped into my head are:

Function Naming Similarity

Function names separated by an '_' are considered by the parser as separate words. Do any of the functions contain the same words? Then group them together.

open_window, close_window, paint_window therefore become grouped functions.

Option:

x use first similar word

x use last similar word

In my case, I don't want open_window and open_door to be related, since open_door should be grouped with close_door.

Other people who reverse their verb-noun ordering may want to choose the other option. So that door_close and door_open would be grouped.

Functional Calling

Functions which call each other tend to be related, and so should be grouped near to each other. This doesn't override Function Naming Similarity which gets the tightest grouping of all.

Therefore, if get_in_car() calls open_door(), sit_on_seat(), and close_door() then they should be grouped near each other.

Functional Calling Order

Order functions in the order in which they are called. So if A calls B and B calls C then there is a clear order in which these functions should be listed.

Option:

x List calling functions first, called functions second

x List called functions first, calling functions second

Option 1 gives you A, B, C. Option 2 gives you C, B, A. Different coders will have difference preferences. I prefer Calling functions to come first.

General Options:

x Functions names use _ separators

x Functions names use bumpyCase

There are some ideas broken down into detail.

I'm not sure how large a task this enhancement would be given the way Tidy is currently coded. It seems like you keep track of variable names and func.endfunc structures, so this enhancement could tie into some of the data you're already collecting.

[Jos]

That's one option.  In the case of functions like: open_something, close_something that would spread out those functions rather than grouping them together.

The concept is that functions which are related to each other should be placed together.

The three ideas that popped into my head are:

Function Naming Similarity

Function names separated by an '_' are considered by the parser as separate words.  Do any of the functions contain the same words?  Then group them together.

open_window, close_window, paint_window therefore become grouped functions.

Option:

x use first similar word

x use last similar word

In my case, I don't want open_window and open_door to be related, since open_door should be grouped with close_door.

Other people who reverse their verb-noun ordering may want to choose the other option.  So that door_close and door_open would be grouped.

Functional Calling

Functions which call each other tend to be related, and so should be grouped near to each other.  This doesn't override Function Naming Similarity which gets the tightest grouping of all.

Therefore, if get_in_car() calls open_door(), sit_on_seat(), and close_door() then they should be grouped near each other.

Functional Calling Order

Order functions in the order in which they are called.  So if A calls B and B calls C then there is a clear order in which these functions should be listed.

Option:

x List calling functions first, called functions second

x List called functions first, calling functions second

Option 1 gives you A, B, C.  Option 2 gives you C, B, A.  Different coders will have difference preferences.  I prefer Calling functions to come first.

General Options:

x Functions names use _ separators

x Functions names use bumpyCase

There are some ideas broken down into detail.

I'm not sure how large a task this enhancement would be given the way Tidy is currently coded.  It seems like you keep track of variable names and func.endfunc structures, so this enhancement could tie into some of the data you're already collecting.

<{POST_SNAPBACK}>

Not sure how easy/difficult it would be... need to think about this.

One other thing needed to be considered is that lots of people are now also using the #Region...#EndRegion pre-processor statements in their scripts, since that enables your code to fold nicely in SciTE .... ( :"> Getting more complex the longer i think about it)

[Valik]

As a non-user of Tidy, my opinion probably doesn't mean much, but I think this idea is kind of absurd. In theory, its a good idea, however, there are some problems.

First and foremost, good style is something to be pro-active about, not lackadaisical. In my opinion, Tidy should lose its usefulness after a couple weeks of experience writing scripts as the responsibility for maintaining clean code should be in your hands. I don't need Tidy because I write clean code as I go.

The second problem is implementing the sorting like you mention is going to enforce a function naming scheme onto people. Theres no possible way to cover every possible way. I could keep JdeB working for a month writing algorithms to sort my functions. And thats what an advanced sorting method would boil down to, JdeB implementing algorithms to sort individuals functions based on criteria they provide. The only generic and reasonable way would be to move all functions to the bottom of the code so that they are seperated from the main executing code. The only viable method I can see for allowing per-user sorting would be to use regular expressions... but that means people have to learn regular expressions and they aren't for everybody. A consistent, generic sorting criterion makes the most sense to me.

As I stated before, however, I don't need/use Tidy so my opinion probably doesn't matter.

[CyberSlug]

Perhaps an alternative:

Show a popup window that has the names of all the functions. Allow the user to sort the list (move items up or down) however he/she sees fit.

I'm kind of in the same boat as Valik, though.

[MHz]

Like any good programmer, I make highly modularized code on any project of size.  This means the code is broken down into many small independent functions.  In practise, it means dozens of small functions stuck in wherever your cursor happens to be at the time, and for a large project, you tend not to order your functions very well, and they quickly become hard to find again.

Difference of opinion. I could not function properly, with such a layout.

A good programmer has a tidy method of coding.

The use of Region and EndRegion, sections your code, which fails with effectiveness, when you have functions in them. When you are coding within a Region, and you wish to create a function, then you fold the section, and write your function below the main body of code. 2 presses of a button, write function, then open Region again, to continue. This is easy, even with thousands of lines of code.

Picking where to write your next function, is also easy with this method. A comment line, can help to section your functions. I recommend not using Region and EndRegion to section functions.

Tidy can be more proactive, then to sort bad coding habits. Tidy's operation and performance, could be hindered by adding bloated code to provide unneeded functionality.

Best habits are good habits IMHO.

[Jos]

As a non-user of Tidy, my opinion probably doesn't mean much, but I think this idea is kind of absurd.  In theory, its a good idea, however, there are some problems. 

First and foremost, good style is something to be pro-active about, not lackadaisical.  In my opinion, Tidy should lose its usefulness after a couple weeks of experience writing scripts as the responsibility for maintaining clean code should be in your hands.  I don't need Tidy because I write clean code as I go.

-snip-

As I stated before, however, I don't need/use Tidy so my opinion probably doesn't matter.

<{POST_SNAPBACK}>

Your opinion does count as far as I am concerned. (no BS and strait to the point(s) you want to make.)

I do not agree that Tidy should loose it usefulness after a few weeks, but that probably also depends on your typing skills.. I do indent my code while typing but still use Tidy every now and then for the Proper function so that the capitalization of functions and variables is consistent.

Thanks all for your input on this one.

I dont think I will be making any changes to Tidy for auto-sorting Func(tions) because I cannot see what logic it would need to follow to ensure that all raised issues will be covered.

The Scripter/programmer should start using the #Region/#EndRegion and Folding capabilities for this and do the move to logical code sections or function sequence themselves. Its a easy one-time-job when SciTE is used.

EDIT: and YES , Tidy.au3 itself still needs to go through that process... it was written before I did the SciTE Lexer....

Edited March 2, 2005 by JdeB

[Valik]

I do not agree that Tidy should loose it usefulness after a few weeks, but that probably also depends on your typing skills..  I do indent my code while typing but still use Tidy every now and then for the Proper function so that the capitalization of functions and variables is consistent.

There's a difference between unintentionally making mistakes like that* and just writing unformatted code knowing you have a crutch like Tidy to make it readable. If used as you describe, its the equivalent of a code-formatting "spell-checker". However, the impression I get from a lot of people is that they use it to do most of the formatting of their code instead of doing it themself. The changes made to a properly formatted script with mistakes is significantly less than the changes made to a poorly formatted script. Its doubtful the mistakes you may make in your scripts will affect the overall readability of the script.

* I manage to avoid making mistakes like you describe by using the complete-word feature almost every time I type a variable or function name. This also instantly shows me if I have made a casing mistake because I may see something like this in the list:

$sMyVariable
$sMyvariable

I can then go to find/replace and fix the mistake with it.

[quaizywabbit]

Rather than come up with complex algorithms to deal with user preferences,

consider the repetitive nature of writing code in the first place.

Maybe the simplest solution would get the best mileage.......

If Tidy encounters a Function in a script, then write that function to a separate script(automatically named after the function), and replace it with an #include <Function.au3> at the beginning of the original script.

Where the function has parameters, then prompt the user to create a "User Call Tip" entry.

Then Functions would be easily reusable in other endeavors...........

Optional, of course..............

Edited March 3, 2005 by quaizywabbit

[Jos]

Rather than come up with complex algorithms to deal with user preferences,

consider the repetitive nature of writing code in the first place.

Maybe the simplest solution would get the best mileage.......

If Tidy encounters a Function in a script, then write that function to a separate script(automatically named after the function), and replace it with an #include <Function.au3> at the beginning of the original script.

Where the function has parameters, then prompt the user to create a "User Call Tip" entry.

Then Functions would be easily reusable in other endeavors...........

Optional, of course..............

<{POST_SNAPBACK}>

I am missing something here....i think ........

Seperating the Func(ions) from the original script into a seperate include file doesn't resolve any of the issues mentioned. They will still be in the sequence that they are in the original script .....

[quaizywabbit]

well, since there could be many variations on where to put them in the script itself,

I figured having a basic option like the above would make the script code easier to follow because the functions themselves wouldn't be in the way. If you're in the habit of commenting your scripts as you go, then you really don't need the entire function in the script anyway.

Also it would lend itself to the habit of creating reusable code functions that Scite has User Call Tips for. Not saying it's the end-all/be-all to the problem......but just a way to simplify things without getting too complicated doing it.

Functions calling other functions directly isn't exactly easy to follow(in a large script), perhaps generate comments next to each associated function call pointing to its dependent function.

So long as it's optional, perhaps with a limited set of choices to configure it...

I'm a Noob...........take it with a grain of salt

Edited March 4, 2005 by quaizywabbit

[MHz]

well, since there could be many variations on where to put them in the script itself,

I figured having a basic option like the above would make the script code easier to follow because the functions themselves wouldn't be in the way. If you're in the habit of commenting your scripts as you go, then you really don't need the entire function in the script anyway.

Also it would lend itself to the habit of creating reusable code functions that Scite has User Call Tips for. Not saying it's the end-all/be-all to the problem......but just a way to simplify things without getting too complicated doing it.

Following the sequence of functions might be dealt with by finding "dependencies" where a function calls another function, so perhaps functions with dependencies need to be in the same external script, listed in the order they are called in the original.  I'm a Noob...........take it with a grain of salt

<{POST_SNAPBACK}>

Disadvantages if added:

Teaches everyone to code poorly?

You would have to run tidy after each function creation, to keep your script readable?

You have to open multiple UDF scripts in Scite to reflect on their content? As newly made UDFs can have bugs.

Can make debugging harder, as chunks of code vanish, from main script, with each use of tidy?

Trusting tidy not to destroy your script, while doing this big manipulation, by any error, whether internal or external. How can you double check that it did it right?

Someone accidently selects this operation, and their script is processed, by this radical concept?

If you don't have the effort to structure your scripts, in the 1st place, how are you going to process all these UDF scriptlets into User Calltips Entries?

Can introduce new bugs into tidy, which affects all, therefore creating more maintaince, and reducing chances of tidy, to expand, in a more productive way?

...

...

Or you just:

Do good code structure, in the 1st place.

Good code structure is the only solution.

This is not a task for Tidy, nor any other.

User Calltips was introduced for versatile UDFs, which you may use often.

Do we need to continue to discuss something that has plenty of negative issues and little or no positives?

[quaizywabbit]

They will still be in the sequence that they are in the original script ..... 

<{POST_SNAPBACK}>

Yes, that's true....but changing the sequence shouldn't be automatic anyway(could break the intended result)

but pulling the function out would allow the user to re-order things by cutting and pasting each Function call, in a script that contains only the logic (stripped down) so it would be much easier to follow.

Tidy is actually quite nice as it is, even if you leave it be, I'm still happy

Maybe my suggestion won't solve the original problems, but it would be a nice option

[quaizywabbit]

Disadvantages if added:

Teaches everyone to code poorly?

You would have to run tidy after each function creation, to keep your script readable?

You have to open multiple UDF scripts in Scite to reflect on their content? As newly made UDFs can have bugs.

Can make debugging harder, as chunks of code vanish, from main script, with each use of tidy?

Trusting tidy not to destroy your script, while doing this big manipulation, by any error, whether internal or external. How can you double check that it did it right?

Someone accidently selects this operation, and their script is processed, by this radical concept?

If you don't have the effort to structure your scripts, in the 1st place, how are you going to process all these UDF scriptlets into User Calltips Entries?

Can introduce new bugs into tidy, which affects all, therefore creating more maintaince, and reducing chances of tidy, to expand, in a more productive way?

...

...

Or you just:

Do good code structure, in the 1st place.

Good code structure is the only solution.

This is not a task for Tidy, nor any other.

User Calltips was introduced for versatile UDFs, which you may use often.

Do we need to continue to discuss something that has plenty of negative issues and little or no positives?

<{POST_SNAPBACK}>

I'm pretty darn sure I said "OPTIONAL" (it could be placed in the "Setup" portion)

I do agree with you in principle( as far as learning good code structuring)

Tidy backs up the original before it changes anything, so that point is moot.

Actually I think in the long run doing this would force me to write "Versatile", understandable, and well commented functions, that don't have dependencies, and predictable return results(good error checking)

I would have to have a solid "gameplan" figured out ahead of time so that my code IS readable, very well commented, and easily understood by others, Before using this proposed option in Tidy.(which would then take me through the steps to make my code re-usable elswhere)

Doesn't really matter much to me anyhow, I'm happy as it is....but it would be a nice "option" <==there, said it again!!

Edited March 4, 2005 by quaizywabbit