Best practice (Part 1) 03 Jul, 2002
Background
There's far too much sloppy Notes & Domino development going on out there. Code is splashed around all over the NSF, no thought has gone into database structure, performance considerations, and so on. This occasional series aims to address this! Part 1 covers centralising your code.
Introduction
How did you come to Notes development? Were you a programmer forced to use Notes when an employer moved to it? Were you a Notes "power user"? Did you just fiddle with it in a bid to pass some exams? Perhaps you were a sys admin with ideas above your station? :-D
Notes is a funny old environment for development. It started out as an extremely proprietary product, a "niche" database application, and has developed into much, much more.
But it's a dangerous development environment. Why? Because of the way code can be so widely distributed within a Notes application.
You can nest code in to form, page and view / folder events. You can tuck it away in agents, shared actions, buttons, hotspots, outline entries, database events.. the list goes on. But just because one can doesn't mean one should.
Why centralise your code?
In a word, "maintainability." Scattering code all over a Notes database does not a happy developer make. Try tracking down that elusive bug. Ever inherited a badly-put-together database? I know I have. Many times. Troubleshooting becomes infinitely less painful when the code is in just one or two places. The advent of shared actions in R5 and script libraries in R4 have helped developers centralise their code, along with other Notes constructs such as sub-forms and agents. Use them!
How should I centralise my code?
There's no point being prescriptive here. Programmers are a notoriously pig-headed bunch, and everyone thinks that their way of doing things is the best. However, I have found that certain rules have helped me no end, and they do seem to really make sense:
- Shared actions
- Form events
- Use script libraries
- Consider a "strings" script library or document
- The database may get translated one day. It's always easier to have all the user-facing text in one place, whether it gets translated by a person or Workbench etc.
- I can edit and review my user messages all in once place
- I can re-use messages and strings (e.g. I always have the same generic text for Messagebox and Dialogbox titles)
An example "libStrings" script library is attached as an LSS file. Simply create a new script library, and then using File / Import, bring the LSS code into it. Have a play, see what you think.
What is wrong with lots of code in shared actions? Where is the advantage in putting the code in an agent?
Perhaps I could understand putting the code in a script library and calling from there but using agents seems a messy way to go.
I think the most important thing is to be consistent. I am trying (in vain) to come up with standards for this kind of thing at work. Stuff like variable naming conventions can make an application turn from a nightmare to a pleasure to maintain.
Is this the first comment?
Mike Bigg#Mike said:
Good question. This way of working, for me, is born out of unhappy circumstances. Shared actions constitute one design element in the NSF. If it corrupts (which mine did), you lose everything. If one agent corrupts, you lose just one hunk of code. So that's why I recommend the approach I outline.
Considering this anew, why store code outside an action? So you can re-use the routine. OK, so for script we can have code in a library and call that from an agent, a form event, a shared action, wherever. But for @formula, if you place the code in an agent, you can call it from all over the place also -- not so if it's stuck in a shared action.
My two reasons why! Thanks for asking. And yes, yours is the first comment. Hurrah!
And yes, in case anyone asks, I know you can only put responses against the main article. I may change that if use warrants it.
Ben Poole#True, I don't quite understand the the thinking behind making shared actions one note in the NSF. Well, maybe I do. But it's still a royal pain, as many have discovered when trying to do whizzy stuff with the API -- plenty of dicussion on the LDD.
As for code in agents, well, why not? Agents and script libraries for all your main code (i.e. more than about 5 lines or so). Nice.
And agreed re naming conventions -- they make life a lot easier in Notes development. Heck, any development!
Ben Poole#I found I was really getting stuck into LotusScript, but one tip they gave me (and I have since picked up from other sites) is to use @Functions instead of LS. The reason? It's a lot easier for the next developer to maintain. That's not to say we shouldn't use LS where it is needed, but why not go for the simpler option first?
The other best practice method I use is to throw absolutely everything at editable documents. I have inherited several applications where there is some obscure bit of coding (ie. HTML) fixed in a field or subform or something. To change the page design in the browser means I have to change the database design, get the template published, etc. Much easier to just change a doc somewhere!Anura Samara#
And that error message was mine anyway -- you were just the poor sap who had to explain what it meant to the Notes Admin chap on the phone
Chris Molloy#