Talk:Programming Conventions
When adding comments please sign them with ~~~~ which inserts your username and the date
Comments
Please use the preview button to show how things look, instead of endless change log entries. Pnaulls
Sorry, yes, I've been in the process of translating the page from HTML so keep noticing things and making amendments. Hopefully the basic structure/layout/conversion is complete now. --Adamr 15:03, 8 Jan 2007 (GMT)
Re, Pnaulls' comment:
The following is opinion of Adam Richardson and may or may not be agreed with by other RISC OS programmers.
I do not intend this page to simply be "my" view of the world. If that were the intention I would have left it on my website. I would rather that it gives a consensus view (if that's possible).
When I first published the article on my website I asked for comments on comp.sys.acorn.programmer and no major issues were raised. The only thing approaching being controversial was the bit about placing modules inside !System.
Peter, are there any specific parts of the document you think ought to be changed/removed?
--Adamr 17:10, 8 Jan 2007 (GMT)
Looks good
In the most part it looks very good and im sure will prove to be very useful. One minor point which I've thought of which might or might not help you - some of the language seems to be a bit informal. There seem to be plenty of people out there who will take a technical document such as this more seriously if the language is formal. For example, the statement "Since, well, ages ago" and the title "Installing Things" (things isnt very technical.)
As I said, only minor, in the most part it looks very useful :) Polas
Style
The style of the article needs to be much more formal. To be suitable as something which has consensus agreement, it needs to avoid first and third person references and casual language. The PRMs et al of course serve as a good model for this. It also needs to as much as possible provide references - for example to style guide pages or other material posted on usenet, etc, etc. --Pnaulls 17:12, 20 Jan 2007
Informal Style
Yes, I agree that the style should be more formal. (It's a hangover from the mood I was in when I wrote the original article.) I will go through and modify the language within the next couple of days. Adamr 13:16, 23 Jan 2007 (GMT)
Authorship
OK, I've made it more formal and it's been a few weeks since my comments about not wanting it to be "my" page, with no objections, so I'll re-word the intro.
Adamr 00:26, 4 Feb 2007 (GMT)
Formality
Despite the previous changes, I still feel the article is far too informal.
Setting System Variables
I don't entirely agree with your example for setting App$Dir vars in !Boot files. !Boot files are only run the first time a particular application is seen, if an identical named copy elsewhere is later opened in the filer: it's !boot file is not run.
Most !Run files run the !Boot file rather than setting the AppName$Dir var themselves. I've never seen an app that uses If "<AppName$Dir>" = "" Then Set AppName$Dir <Obey$Dir> in it's !Boot file.
If I manually double click a !boot file, it means I want this copy of an app to be my currently preffered copy, I'd be pretty miffed if this was defeated by a If "<AppName$Dir>" = statement.
IvanDobski 13:09, 21 Feb 2007 (GMT)
For an example of not setting everything in the !Boot file, see the NetSurf !Boot file, though it doesn't completely match the (simple) rule given here.
Also, the current version of the RiscPkg policy manual states that apps which are going to be packaged should act like this. (See towards the end of the manual.)
From the point of view of manually double-clicking a !Boot file. Have the actions of !Boot files ever been sufficiently defined that you'd expect it to set up certain things? I know I've seen lots of !Boot files which only contain an iconsprites line. (Also, I wouldn't expect any user to be opening an application directory and doing anything inside.)
Adamr 11:52, 22 Feb 2007 (GMT)
I should emphasise I am only referring to App$Dir variables, I quite agree about filetypes other sysvars etc.
The RiscPkg manual says... "System variables with previously set values should not be altered." Now for an application !Adam it's !Boot file would only be run by the filer the first time it's seen, so it's implicit that Adam$Dir doesn't yet exist. The test is unnecessary. If another !Adam is seen by the filer later, it's !Boot file will not be run, so the test is again unnecessary. Although the test is largely harmless you are giving the incorrect impression that !Boot files are run every time an app is seen.
It's a distinct advantage to call !Boot from !Run, as it avoids duplication in the !Run file, and thus the possibility of introducing problems from not keeping both files synchronised.
In the early days of RISC OS programmers were discouraged from calling !Boot files from !Run, because this caused poor performance on Econet. On modern machines there isn't much point.
Unless there is some issue I'm unaware of I don't see any reason why Set App$Dir needs to be protected by an If statement.
Netsurf's !Boot definitely doesn't match the simple rule, it includes the line
Set NetSurf$Dir <Obey$Dir> ;)
IvanDobski 11:17, 23 Feb 2007 (GMT)
Well, I certainly agree that it is much more important that people worry about filetypes, runtypes etc so I've altered the example with that in mind.
With regards the fact that the filer is implicitly doing the conditional bit - if the condition is there anyway, why not make it explicit? The current situation means that there might be two potential outcome from the same file depending how it is called (e.g. from the filer, from an obey script, from an application launcher, by RiscPkg...)
Also, I don't see any reason why people can't call !Boot from !Run.
Adamr 17:35, 25 Feb 2007 (GMT)
I've tried to give a more balanced view on the necessity of certain files (whom !Boot) which I think addresses the comments above better.
joty 13:05, 11 May 2008 (BST)
Linking to software
I personally feel that all links to pieces of software should link to a site wiki article about said software.
There are 2 reasons for this:
- A user can find out a little more about the software without leaving the wiki
- If details about a product change (eg: URL), only one article needs to be updated
Jymbob 22:49, 16 Apr 2007 (BST)
Sure. (Though I do personally find links to blank wiki pages annoying when they could just be links to the homepage ;) )
There was some discussion about this on Talk:Recommended software. I think if a standard template for each app were used it would be good.
Adamr 00:57, 17 Apr 2007 (BST)
References
It took me a couple of minutes to realise that (SG:106) meant Style Guide page 106 (I nearly deleted those SG lines ;-)). Any suggestions to make this more clear ? Shall we create a new Wiki page 'Style Guide' (and perhaps 'PRM') ?
joty 13:05, 11 May 2008 (BST)
