objectscript / cos-guidelines Goto Github PK

instead of with getting next index in the end of loop

set ind=$order(array(""))
for {
    quit:ind=""

    /// some code here
    set ind=$order(array(ind))
}

should be

set ind=""
for {
    set ind=$order(array(ind))
    quit:ind=""

    /// some code here
}

But why? What is the purpose of it?

I think this is a cool syntax feature which allow to refer classes inside the package without mentioning the package name itself. It is very helpful if someday you want to rename your package, which happened once in one of my projects (%WebTerminal -> WebTerminal).

Bad code comments

    if (x) { //If x is true then continue on
        do $zu(45,$zu(27,$ZCVT(x,"UTF8"),a,t+1))
        write "Sucsess" //tell the user we did it
        return x+1 //End the function and give them the increment
    }

Using short-curcuit logical operators ("&&" and "||") instead of regular ("&" and "!")

• Use documatic formatting (basically HTML)
• All that can be in a signature must be in a signature, eg. ClassMethod Read(FileName As %String, Length As %Integer(MINLEN=1) = 32656, ByRef Status As %Status) As %String
• Do not duplicate in documentation what is in a signature
  • Length is a positive integer
  • Default length is 32656
  • etc - it's all obvious from a signature
• Documentation is for everything else: This methods returns first Length characters from FileName, check Status for errors
• Signature must correspond to what's inside the method
• Ideally, signatures are consistent across project
  • Return status (but not, for example some methods return status, some - exception)
  • etc
• Provide defaults for unrequited parameters
• Do not provide defaults for main (id/oref etc) parameters

http://stackoverflow.com/questions/35495279/

i,j - to use in iterators
obj - basic var if there is only one object inside a method

I propose mandatory full name of class (except %Library package)

Set obj = do ##class(Sample.Person).%New(initexpresion)

instead of

Set obj = do ##class(Person).%New(initexpresion)

One exception for this rule, for some of macrodefenitions like this:

#define NewTempGN(%gn,%i) set %i=$i(^CacheTemp.MyApp),%gn=$name(^CacheTemp.MyApp(%i))

then in code, such code with space after comma will cause an compile error, because spaces here is valuable too, and will appear as is in generated code.

$$$NewTempGN(gn, ii)

I propose mandatory spaces before and after assignment:

set a = 1 
for i = 1:1:10 {

Instead of current:

for i=1:1:10

Let's make first letter capital

If (expression) {
  Do ##class(Sample).%New(initexpresion)
   For i=1:1:10 {
    Write something,!
  }
 }

look better than

 if (expression) {
  do ##class(Sample).%New(initexpresion)
   for i=1:1:10 {
    write something,!
  }
 }

What about functions with long names?

$listfromstring()

or

$lfs

So, whats the variable naming scheme?

set i
set CountIndex

@ZitRos made good point.
If these guidelines are for newcomers then we should explain what does "dotted syntax" means.

Or provide some reference to the samples of it. E.g. http://docs.intersystems.com/cache20152/csp/docbook/DocBook.UI.Page.cls?KEY=RCOS_cdo_legacy

The only remaining change to make in the cheat sheet is using italics for placeholders throughout. Especially after the last addition:
Set object = ##class(package.class).IndexNameOpen(value, concurrency, .status)
which should really be:
Set object = ##class(package.class)._IndexName_Open(value, concurrency, .status)

But we have an Issue, because it's messy in md to use italics within code, and the output is not perfect:
Set object = ##class(package.class).IndexNameOpen(value, concurrency, .status)

And I suppose that the best way to do global search and replace is to use GitHub Desktop and a different editor than the one in GitHub...