forums.silverfrost.com Forum Index forums.silverfrost.com
Welcome to the Silverfrost forums
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

Documentation of Error Messages ... and Bugs

 
Post new topic   Reply to topic    forums.silverfrost.com Forum Index -> Suggestions
View previous topic :: View next topic  
Author Message
John-Silver



Joined: 30 Jul 2013
Posts: 633

PostPosted: Fri Mar 13, 2015 5:54 pm    Post subject: Documentation of Error Messages ... and Bugs Reply with quote

Following a few recent 'observations' about indecipherable error messages
e.g. here: http://forums.silverfrost.com/viewtopic.php?p=17565#17565
I have the following thoughts.

Firstly I'd agree about the need generally for better more 'human' error messages within FTN95 , however to be fair I think its a general 'disease' amongst computer programmers in general and not specific to FTN95.

Having said that, What would be good, some would say Essential, would be a complete list of error messages documented in the manuals (and/or in a seperate file), a sort of 'FTN95 Error Messages Encyclopaedia' if you like, where suggestions like Dan's could be easily added in a simple and regular update which would be better than the existing situation.
I don't know how the ftn95 error messages are set up in the code but if defined in a 'Data' file (and not spread thoughout the program) such a document could be easy to generate. Errors should really carry a unique number too , for quick reference, but not sure how easy that would be to apply retrospectively.
Users could easily suggest human descriptive texts for any indecipherable hyroglyphics (a la Dan) which would be easily and regularly updated with minimum effort by Paul et al.
It would also serve as reference for periodic updates of the error messages themselves to a more understandable form at appropriate major releases.

... oh, and while we're at it, any self-respecting program should also have a bug (known errors if you like) list. Every computer program has errors and imo a long list doesn't mean the program is bad, more that the program writers are diligent and in control of their program ! (well, diligent at least Wink )

..... idealistic practices maybe, but its all part of good QA practices ...... food for thought (and hopefully implementation in some way) for Paul & Co.[url][/url]
Back to top
View user's profile Send private message
LitusSaxonicum



Joined: 23 Aug 2005
Posts: 1683
Location: Yateley, Hants, UK

PostPosted: Sat Mar 14, 2015 2:27 pm    Post subject: Reply with quote

Rushing to the defence of Silverfrost ...

FTN95's diagnostic messages are probably the Gold Standard. Most of what you call indecypherable is the trackback, giving you source code line numbers.

When I look in FTN95.CHM, under %tl in the format code reference, the omission is to state that if N=1 it still needs to be there. I also wondered about describing the position as 'REAL' - it is DOUBLE PRECISION in the example, and also for %ta.

The injunction to read the manual fails when:

The manual is incomplete
The manual is incorrect
The manual isn't clear

Provided that the format string in a WINIO@ call is a valid string, it passes the compiler, and it is only when it is interpreted into a window at runtime that errors such as this are detected. Sure it's irritating, but the routine trackback tells you exactly where it failed.
Back to top
View user's profile Send private message
wahorger



Joined: 13 Oct 2014
Posts: 395
Location: Morrison, CO

PostPosted: Sat Mar 14, 2015 4:36 pm    Post subject: Reply with quote

As far as the %tl is concerned, I guess one could have assumed that a capitalized "N" means that the number is required, even if it is "1".

Truly, this is an obfuscation of intent. If a parameter is required, the documentation should state this fact, regardless of convention.

I took a look at the documentation, and can find no description of the differences of "n" and "N" that would be found in the documentation. Similarly, for ANY combination of single letters either capitalized or not. Should I see this in the future, I will now know/assume that the parameter is required.

And, the traceback certainly does show the line at which the problem was detected. But the message of "Missing numeric parameter" is, at best, not precise. Again, better documentation == better products.

In spite of all of this, I love the level of documentation that is available with FTN95 and ClearWin+. It has been a lifesaver for me and my work. I am much further along in my re-development because of what is available on-line.

That being said, the point being made by Dan and John is that any and all documentation can be made better and more usable. And here are several of us who would love to help, as long as it is in a helpful, constructive way that is of benefit to SilverFrost. [/u]
Back to top
View user's profile Send private message Visit poster's website
Display posts from previous:   
Post new topic   Reply to topic    forums.silverfrost.com Forum Index -> Suggestions All times are GMT + 1 Hour
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group