Best practice (Part 1)


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.


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
Don't dump loads of code in shared actions. If you need to do more than a couple of lines'-worth of @formula or Lotusscript, consider placing the code in an agent (or script library), and have your button call that instead. The beauty of shared actions is not having to code identical action buttons over and over, but the code should still be centralised.
  • Form events
In larger applications, rather than dumping all your code in the relevant events, consider calling generic script library routines which cover common events such as Querysave validation routines, edit authentication, and so on.
  • Use script libraries
These are indispensable. Really think about your routines. Make them as generic / modular as possible. Notes isn't exactly an object-oriented environment (!), but that doesn't mean you can't start to think that way. Consider having a "UI" script library that handles form validation, another that comprises solely "back-end" code that can be safely used by agents that may run in the background or be used as scheduled processes, and so on. If it looks like your code could be used in more than one place, dump it in a library, don't squirrel it away into an agent. Let the library have it, and get the agent to call the routine.
  • Consider a "strings" script library or document
This is a particular favourite of mine. I like to have a "strings" library which contains a generic unexpected error handler routine that all my Lotusscript can call, plus in the (Declarations) section, a bunch of constants which represent all my user messages invoked in Lotusscript somewhere in the application. I do this for a few reasons:

- 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.



  1. 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#
  2. Mike said:

    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.

    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#
  3. Fair point If you could store Shared Actions as separate hunks of code like subforms or agents that could be dropped into any design element rather than getting lumped together in $ACTIONS that would be better. Didn't you have a backup to restore from when $ACTIONS got corrupted? ;)Mike Bigg#
  4. 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#
  5. I work exclusively on web applications, separately to the rest of the Notes developers in this organisation.

    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#
  6. Inherited dodgy dbs eh? Now what makes me feel you may be refering to my beautiful suite of applications I left you before doing the Frank Boff to Oz? Frankly I think you wrote this whole article because you didn't understand the coding genius behind my killer functions such as "Dave's amazing agent" and the "You haven't created a profile document you fecking edjit" error trapper. dim dave as notes wanker…ginger binger#
  7. … I wasn't referring to your stuff. Who could ever diss "Dave's amazing agent" eh?

    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

    ;-) Ben Poole#

  8. I seem to remember an 'Agent 007', as well. Who wrote that one?
    Chris Molloy#
  9. I'm lucky (I think !) enough to be building an App from scratch, so am trying to apply every best design practice I can: from my base_href fields to my Classes I have written, clear comments etc. I just found the tip of sticking my message strings as Constants in a Script Lib. Doh! Mine were all over the place. I don't know how many people comment\ visit your site, but along with codestore\ notestips and yourself I visit your site daily and you are all a constant source of knowledge. To someone like me, and I am sure plenty of other developers, who are trying to stay on top of all the different technologies, XML, Java, HTML… your sites are invaluable. For an ex-pat in the US, the humour's refreshing as well.nick#

Comments on this post are now closed.


I’m a software architect / developer / general IT wrangler specialising in web, mobile web and middleware using things like node.js, Java, C#, PHP, HTML5 and more.

Best described as a simpleton, but kindly. You can read more here.

File Attachment Icon