PDA

View Full Version : Feature Request: Comments Box for Elements and Buttons


NeoMorph
August 23rd, 2007, 01:08 AM
One of my complaints about NetRemote is that the example ccf's don't have enough comments in them and too many elements have default names. Well I thought instead of complaining I would do something about it and began to go through the mce1024x768 example and adding comments in when I realised what would be an excellent addition for coders.

How about a short single line comment attached to elements for use in the left hand tree and a larger comments tab for when you open the F2 properties!

I was a coder for quite a few years and when I went through training back in the 70's I was taught to add comments as most likely even though I wrote a program myself that after a couple of years even though I wrote it myself I would forget the reason for doing something in that program and it would make any alterations and/or additions more time consuming because I would have to take take extra time trying to learn the code and why I did certain things before I did the new work. Commenting code lets you quickly learn what certain code is and shortens familiarisation time and helps others who may be required to do work with your code become familiar too.

The comments boxes would allow you to put explanations for what the button or frame does. One of the really confusing parts of the NetRemote learning process I found was discovering what the actual elements do in the example ccf's.

For example the slider button component starts off as a basic button before being changed on the Position/Advanced tab... then it looks like a frame element but with an up/down image. I banged my head on the wall several times before I figured that it starts off as a button and not a frame. Once I realised to look for the dual button up/down states at the bottom I then got confused as to where the lua that controlled the slider was as it wasn't connected to the slider. I didn't know what to look for in the help file and so the examples I found didn't help me. Having a comment box explaining the use of sliders would have helped greatly.

Here is what I would have put on an example slider tutorial.


This slider button is configured on the Position/Advanced tab. The "Component" dropdown box shows it is a slider button by displaying "NRBasic:Slider Thumb Component" and the "Set Properties" button next to it allows you to set the variable (VAR) which is controlled by the slider, the starting position of the slider (STARTVALUE), the minimum slider value returned (MIN) and the maximum slider value returned (MAX). It also allows you to choose whether to send the value only when you release the slider button or continuously (OPTIONS: Send on release only) and also the frequency the slider value is sent using the THROTTLE value.

Some sliders control inbuilt NetRemote parameters (like here MP.GAC[8].CurrentPage which controls the page of album or artist results) and others control values that are defined and monitored in Lua programming using NetRemote.RegisterVariableWatch commands (which will be described in the relevant custom slider button). In this case where the value you want to use is a NetRemote parameter the MIN value should be set to 1 and the MAX value should be set to 1000. The actual values will be set by the NetRemote parameter itself by making itself a ratio of 1000...

For this example moving the slider if there are only 2 pages of results will work as follows...
If the value returned by the slider is between 1 and 500 it will show page 1.
If the value returned by the slider is between 501 and 1000 it will show page 2.

For this example moving the slider if there are only 3 pages of results will work as follows...
If the value returned by the slider is between 1 and 333 it will show page 1.
If the value returned by the slider is between 334 and 666 it will show page 2.
If the value returned by the slider is between 667 and 1000 it will show page 3.


If the above comments was in a Comments box or tab it would have helped me grasp the idea of sliders a lot quicker. Currently it means looking at the ccf and then having to search through the help files and trying to figure out how the heck the thing manages to control the page - it took me a couple of days because of having to figure out that the missing actions page didn't mean it was an element that did nothing. I was actually trying to figure out why the slider frame did nothing would you believe. DOH! :rolleyes: I then spent ages looking through the main Lua for the NetRemote.RegisterWatch that was called by the above slider... and obviously failed to find it because the above slider controlled the NR parameter directly. Hence the screaming need for comments... to stop new users screaming at NR that is ;)

Edit: If you do add the comments boxes I would be willing to volunteer to add comments to mce1024x768.ccf for all the stuff I've learned recently through blood, sweat and loads of tears... Hopefully my recent experience learning NRD coding will come to good use helping new users. I still have a ways to go but am gaining ground but so unfortunately my avatars "ODNAQA" will still be in effect for quite a while yet (that's "Oh Darn, NeoMorph's Asking Questions Again")
Rob H
August 23rd, 2007, 07:55 AM
That sounds like a good idea, but it will increase the size of a CCF file of course.
NeoMorph
August 23rd, 2007, 01:25 PM
That sounds like a good idea, but it will increase the size of a CCF file of course.

They would only have large explanations for example CCFs to help new users get to grips with how CCF files work. For most coders a sentence or two would help understanding at a later date.

A possibility way to optimise operational CCF's would be to have the comments boxes link to a seperate help file so that the distributed CCF could run without the comments file at runtime but would still have them available whenever you needed to upgrade or bug-fix the code.
Barf
August 25th, 2007, 03:33 AM
I strongly support the idea of allowing comments in CCFs. Actually, the present lack thereof is one of the reasons why I am considering dumping NR...


... but it will increase the size of a CCF file of course.
will probably only be an issue in very rare cases. NeoMorph has already suggested a fix,

A possibility way to optimise operational CCF's would be to have the comments boxes link to a seperate help file so that the distributed CCF could run without the comments file at runtime but would still have them available whenever you needed to upgrade or bug-fix the code.
which however is not without drawbacks: need to handle (and distribute) two files instead of two. (No, zip does not solve.) Another suggestion would be to provide a strip-comments utility, for the rare cases that contained comments would be a memory or performance penalty.
NeoMorph
August 27th, 2007, 05:15 AM
(snip)which however is not without drawbacks: need to handle (and distribute) two files instead of two. (No, zip does not solve.) Another suggestion would be to provide a strip-comments utility, for the rare cases that contained comments would be a memory or performance penalty.

It would be most likely three files... the main Lua file is already separate from the CCF (try downloading some of the examples and you will see... or just make a new ccf then open the main Lua script page by right clicking on "System" in the NRD treeview of your CCF and select "Edit Lua script file". Enter whatever text you want in there and click ok... save the CCF and check the directory in windows explorer. If you saved the CCF as "Test1.CCF" you will also find another file called "Test1.lua".

Hopefully if Promixis used the help file idea it could be saved as XML so you would have a third file called Test1.xml. Having it an xml file would be great if you just want to go in and edit the comments separate from NRD. If you did it in NRD you would have to open each and every element to edit the comments. Having a button called "Turn On Amp" in your CCF could be made a group in xml like this...

...
</Turn Off XBOX>

<Turn On Amp>
<Short Comment>Turns on Amplifier</Short Comment>
<Long Comment>Turns on Denon Amplifier in the living room and switches to Video</Long Comment>
</Turn On Amp>

<Turn On Main Light 1>
...


Another addon to this would be tooltips when going over the tree that linked to the short or long comments. It would help remind you what a certain element is for...

For example in your new-pro480x640.ccf on the MediaBridge group, Covers page there is an element called "Unnamed Element" with a sub-element called [Lua] with a further sub-element called "New Button". For an example CCF it doesn't help new users when they look at these entries and finally find the "New Button" and it appears to have nothing in it. Not even labelling the elements seems like the CCF was thrown together quickly and wasn't finished. I did that once when I was coding for a large computer centre and my project leader tore me a new one when he saw the code...


"OK (my name)... what the heck (made nicer for forum) is some other programmer going to think when they come in and have to fix or update your code... with you using default names for objects and variables, like Integer1 or String3, it's going to take the other programmers *$%£&ing ages just to figure out what the $%£&ing variables actually are used for and it ends up slowing them down and creating more costs to the company because it takes him X number hour or days just to figure out your messed up code before they can even START to think of updating or fixing your mess.

If there is one thing you must always remember no matter what the computer language you use... use informative names for your *$%£&ing variables and objects and comment, comment and comment your work. If you had a choice between String3 and Address3 which would you understand first? Oh and if you are unsure if you have enough comments... ADD MORE. It may take up a small amount of time now but it will save a heck of a lot more time at a later date."

:eek:

Somehow that outburst from my project leader stuck in my head somehow... I wonder why? :o I was 18 at the time and in my first programming job so I learned at an early age so it kind of impressed me why it was necessary to comment and name variables properly... I think it took me two days to fix my program and even then I realised how using comments and informative naming works well especially when someone else is going to work on your code at a later date. I'd only done the code the week before and I had trouble remembering what Integer33 was for

I'm sorry if the criticism seems harsh but I'm trying to be constructive here and hopefully help you help new users learn your software and even more important get you more sales. Having example CCFs with default names and zero comments doesn't help new users one bit. Change the names to something informative like "Frame for retrieved Album/Artist results" instead of "New Frame" is better than finding several "New Frame" element entries in the NRD design tree and trying to figure out what you are actually looking at. Having "Unnamed element" is even worse...

Renaming all the elements called "New Page", "New Button", "Unnamed Element" and "[Lua]" in your example CCF's would go a long way to helping people to learn to use the software as it would make it quicker for them to understand what they are looking at. Add the comments and it would most likely cut learning time down by a factor of 10.
Rob H
August 27th, 2007, 05:58 AM
I'd agree with most of that, but I'd tend to cut down on the number of comments in program code to explaining how the code fits together and how to use it. A comment in a function that explains a tricky piece of code is a "code smell" that tells me that that bit of code should be abstracted into a function of its own with a good name.

I like the idea of using XML although I'm not sure that the node should be called <Turn on lamp>. I'd say more something like <Button Name = "Turn on lamp">.

Personally I'd like to drop CCF format entirely and have the entire file as XML. The main reason for not doing this is that it might slow things down on the PPC, unless there are some newer libs for processing XML on a PPC than when Ben last looked at this. This is what Philips did for the newer Prontos (actually the PCF format is a zip file containing the XML and the related graphics). One possible way around this is to have two formats, the XML one and the existing CCF format. Editing would be done on the XML format and it could also be 'compiled' into CCF format for the PPC.
NeoMorph
August 27th, 2007, 04:12 PM
Like I said before, only the examples distributed with NR would have a large comment content where proper CCFs that users develop would have code smells as you call them. The reason my old boss used to like a lot of comments was because a single program would have quite a number of coders working on the same files and each one had to learn the code before updating it. As the time period from first coder could be as much as 10 years apart it helped to understand the original coders ideas and methodology.

One thing we used to abhor back in the day was altered gotos in COBOL... to such a degree that we managed to finally get them totally abolished and whenever we updated an old program we used to rip out all the old altered gotos or do a total re-write if it wasn't possible within a reasonable amount of time... the reason for this was because it was next to impossible to follow program flow and doing dry runs was a pain in the backside. The only way we could even figure out what was going on was due to loads of comments. *shudders*
Rob H
August 28th, 2007, 01:15 AM
In my programming career I've been lucky enough to avoid COBOL, but I can understand why you'd need lots of comments (as if COBOL wasn't wordy enough!). One other place that I can justify plentiful comments is in assembler programming of course.

My main concern with comments is that people are lazy (I include myself here of course), and don't always update the comments to reflect changes to the code: at that point they become positively dangerous.
NeoMorph
August 28th, 2007, 11:02 AM
In my programming career I've been lucky enough to avoid COBOL, but I can understand why you'd need lots of comments (as if COBOL wasn't wordy enough!). One other place that I can justify plentiful comments is in assembler programming of course.

My main concern with comments is that people are lazy (I include myself here of course), and don't always update the comments to reflect changes to the code: at that point they become positively dangerous.

COBOL - Common or Bus.. err BORING Orientated Language.

I hated the thing. I had started programming by learning ALGOL and COBOL was a sheer borefest. You needed like 1000 lines just to initialise the damn thing heh (ok maybe an exaggeration but at times it felt like it).

I can't see why comments in CCF's would be dangerous... in C++ definately but for something like your CCF's I could see little downsides to many upsides to having comments available.

Oh on the XML tag format thing... can you tell I've never used XML in my life... ;) It was just becoming the "in thing" when my disability meant I had to pack in programming as a job due to being stoned on painkillers all the time. Since then I've only dabbled and messed about with VB, PHP and of course Lua for NR.
Rob H
August 28th, 2007, 11:30 AM
Oh, I agree that there wouldn't be such a problem with comments in CCF files, although I'm not looking forward to putting them there! :)
vitello
August 28th, 2007, 08:29 PM
Like NeoMorph I have also been programing for a long time (since the 70's and this is still what I do) and I am a firm believer in comments and documentation. I know that is extra work, but if users are to learn form the ccf files and from the lua files, then over documentation is much much better than under documentation. If coding is for internal use put as few comments as you want, but if you want users to learn and enjoy what you are doing please explain what is going on. I mean, examples are meant to have more info that production code. If you don't want to comment the lua or ccf files then add detailed examples, tutorials, documentation. There would most likely be fewer questions along the lines "how does this work ...?" and more forum discussion of fun stuff.

To work out how the Flatstyle Music and DM ccf worked for Insteon lighting I had to trace though much of the DM lua code. I do this for a living and I had some free time at that point, but it still was a lot of work and I only got the DM version of lighting working on my PC client, not on my PPC. I worked out my own coding that works on both. In looking at the Promixis ccf download site, there are only two posts this year, and both are from JLee. To me this says that NRD isn't being used. It is great piece of software, but personally I think the problem is lack of documentation and working examples. I expected to go from my G4 setup to a NetRemote interface is a few weeks or maybe a month. Six months later I'm still only partly done. Now part of this is because I learned as I went along that I could get finer two-way control in NetRemote than I expected and my ccf does more that I originally planned on, but most of the time was spent trying things that didn't work. I love the ccf design I have been working. Part of it is a detailed floorplan of my home with my Insteon lights animated with different colors so I can tell at a glance not only what lights are on, but their brightness. I've stopped development for now until the image degradation problem is fixed. I have a lot of ideas I wanted to try out and I don't want to constantly repalce all of the bitmaps.

I would much rather spend time going over examples than doing trial and error. Please, please bump up the priority on explaining how things work and how to use this great software.

Peter
NeoMorph
August 29th, 2007, 03:29 AM
(snip)... I mean, examples are meant to have more info that production code. If you don't want to comment the lua or ccf files then add detailed examples, tutorials, documentation. There would most likely be fewer questions along the lines "how does this work ...?" and more forum discussion of fun stuff.
(snip)

Here, here.

The capabilities of NR are brilliant... it's just getting round the fact that it's 60% guess, 10% learn from the current examples, 5% learn from the manual, 25% get the answers from the forum. Once you get over the huge hurdle of understanding the way NR works it alters that you use the manual more. I just wonder how many fail to get over that first hurdle (I nearly gave up several times and I was a programmer).


(Oh, I agree that there wouldn't be such a problem with comments in CCF files, although I'm not looking forward to putting them there! :)
:D
At least you are honest mate... but I hope you do get around to doing it. I'd love to see the program purchase history after you get the comments code in along with some nice examples like a new-pro2_480x640.ccf with help explaining how it works... and Flatstyle too. That has some lovely code in it that can baffle some but is awsome when you understand it.