Standards document for Objectscript developers

Answers

When it comes to creating development/coding standards for your company, there are a few key things to keep in mind.  First the standards document should account for both development standards, as well as, coding standards.

Here are some thoughts/suggestions to consider:   Disclaimer:  The content listed below is just ideas and not necessarily a proposal of what your development/coding standards should be.

  1. The document should consider code that will be added/modified to existing legacy code versus new code that is being added to the application.  My recommendation for the legacy code is to insure any new code added to the legacy code try to maintain the coding style of the legacy code so the code does not become hard to read.  Example:  If the legacy code uses the old Mumps style of coding with line tags, goto, short variable names (i.e. X, Y, Z, I, J, K, PN, etc...), then I do not recommend adding Cache ObjectScript (COS) procedure blocks within the legacy code, because if added within code that contains things like structured DOs, then it could have impact on process flow, variable scoping, etc...;  If you do decide that new code (i.e. new methods) added to legacy code should follow COS standards, then consider having a coding standards rule telling programmers to add new COS style code at the end of the legacy routine - to keep all the COS style coding at the end of the routine, so the core legacy code looks consistent - it helps with reading the code for support and maintenance.   And it would be ok to allow the legacy code to call to classes/methods or to use new intrinsic functions ($Case, $Replace, etc...)
  2. The document should outline the recommended Development Standards vs. Coding Standards
    • Development Standards would be things like how to implement the various frameworks for things like error handling, database maintenance auditing, web services, handing of I/O, each definition page must have a corresponding inquiry, rules around creating custom components/composites/data types, etc...
    • Coding Standards would be things like:
      • naming conventions for packages, classes, routines, properties
      • type of comments to use
      • allow use of blank lines for readability
      • Commands should be in mixed case (or all uppercase or all lowercase - whatever is preferred for your company)
      • all Commands should be expanded (or collapsed)
      • maybe a rule about line length
      • rules around use of streams
      • rules around use of triggers
      • rules around SQL queries (dynamic? class? embedded?)
      • date/time formats
      • control structures
        • IF - comma versus double ampersand or exclamation point versus double vertical bar
        • Do-While
        • For
        • While
      • transaction processing (be careful not to mix old Mumps based TP with Cache Objects TP)
      • Should Xecute be allowed?  Can be hard to debug/support
      • Post Conditionals
      • locking (this can have information in both the development standards and the coding standards)
      • and on...
      • and on....
  3. Depending on the type of applications that your company has, there may need to be standards for the old type of UI (green screen/roll-n-scroll) versus UI for web-based applications.   There would be a whole separate list of recommendations around web-based development standards versus older Mumps based applications.
  4. When considering things such as Error Handling - there should be standards for how to deal with error handling for web-based applications, web services, and old Mumps based applications.  As you know, error handling for web-based applications can be more challenging because of the number of layers that could be involved (client, middleware (could be many layers), server (could also be many layers))
  5. Standards around database design
  6. Standards around MVC
  7. code should be modular and methods should perform a specific task.  Do not try and create methods that do everything (UI layout, validation, database updates, etc...) in a single method.
  8. There may need to be a separate standards sub-section on use of procedure blocks, since there are many things to consider when using procedure blocks
  9. and on....
  10. and on....

Any development/coding standards document could be fairly lengthy.  But as everyone can agree, standards are very important to insure applications are implemented in a consistent manner, where the code is supportable, maintainable, and reusable.  But it is also important to allow some flexibility with the standards to allow programmers the opportunity to be innovative with how they develop code.  The challenge is finding the perfect balance.

Hope this helps and Have a Great Day!!!  Go Team!!

Happy Coding!!

Hi John,

Thanks for highlighting the difference between development standards and coding standards. It looks like I need to update my document!

Cheers

Mike

 

Thanks Eduard, this is a good starting point for my document.

I notice that you allow methods to return objects rather than %Status. I have looked at a lot of InterSystems Ensemble code over the years, and the general style is to always return a %Status and any object oRefs required are passed out as Output parameters. Would you say that this is the most common style?

Regards Mike

 

Thank you very much Eduard, I know there are some utilities that can create a printable version, just wondering -- do you have a static version of this handy by chance? thanks,

Here are ones we used at Dimas ltdcode_standards.doc code_standards_cheat_sheet.doc

 

Thanks Sergei, this is exactly what I was looking for.

I notice that we already differ from your standard quite a bit. I have looked at a lot of InterSystems Ensemble code over the years and have sort of inherited their style.

We also insist on using #dim for all variables to prevent spelling mistakes causing problems.

Regards Mike