Skip to content

Latest commit

 

History

History
800 lines (607 loc) · 24.6 KB

README_en.md

File metadata and controls

800 lines (607 loc) · 24.6 KB

Style Guide for GeneXus Development

by Daniel Monza

Creative Commons License

For corrections or improvements, please use the github issues or email us at info@sincrum.com. If you are going to submit a change, please read the contributing guide first.

Published changes are recorded in the changelog, and proposed rules not yet incorporated in the roadmap.

Objectives

This guide was written with the following objectives in mind:

  1. Convey best practices for GeneXus development.
  2. Standardize the code that is written. Since there are as many ways to program as there are programmers, we try to make the source code easier to read.
  3. Spread good coding practices and the new features of the language.

Table of Contents

  1. Naming
  2. Enumerated Domains
  3. Indent and Spacing
  4. Structured Data Types
  5. Strings
  6. Comments
  7. Commands and Functions
  8. Parameters
  9. Subroutines
  10. Good Practices
  11. Resources
  12. Companies that use this guide
  13. Translation
  14. Collaborators
  15. License
  16. Amendments

Naming

  • 1.1 Names must be descriptive.

    The goal is to name things in a self-descriptive way.

    // bad
    Proc: CliCre
    
    // good
    Proc: ClientCreate

  • 1.2 Use PascalCase when naming objects, attributes and variables.

    // bad
    clientcreate
    
    // good
    ClientCreate

  • 1.3 Do not use an underscore at the beginning or end of any object, attribute or variable name.

    This could misguide a programmer more familiar with other languages into assuming the name has some privacy meaning.

    // bad
    &_ClientName = "John Doe"
    &ClientName_ = "John Doe"
    Proc: _ClientCreate
    
    // good
    &ClientName = "John Doe"

  • 1.4 Name enumerated domains without abbreviating, starting with the entity in singular and then the enumerated qualifier in plural. Enumerated values must be specified in singular.

    This is done so that attributes don't collide with enumerated domains.

    // bad
    DocumentType
    DocumentsType
    DocumentsTypes
    DocTypes
    
    // good
    DocumentTypes { Sale, Purchase, etc}
    DocumentModes { Credit, Debit}

  • 1.5 Name related procedures as Entity + Attribute (depending on the case) + Complement + Action.

    This makes it possible to group objects of the same entity in the object selection, among other things. Typical actions are Get, Set, Load (for an SDT), Insert, Update, Delete, etc. The difference between Set and Update is that Set refers to an attribute while Update refers to an entity.

    // bad
    CreCli
    UpsertClient
    DateClient
    
    // good
    ClientUpsert
    ClientDelete
    ClientModifiedDateGet
    ClientModifiedDateSet
    DocumentRecalculate

  • 1.6 Use GIK nomenclature to name attributes. Attributes may be created without the 3-character limit if the name does not exceed 20 characters and it improves comprehension.

    This has been the standard since the beginnings of GeneXus.

    // bad
    CreCliDte
    DateCreatedClient
    
    // good
    CliCreDte
    
    // better
    ClientCreatedDate

  • 1.7 Transactions should be named after the entity in singular.

    This is defined this way because in the GeneXus community it is clear that it works better, for example when working with Business Component. It is also required by some GeneXus patterns for their correct display (e.g. K2BTools).

    // bad
    Trn:Products
    Trn:Clients
    
    // good
    Trn:Client
    Trn:Product

Back to Top

Indent and Spacing

  • 2.1 Use tabs instead of "spaces". This way each developer can visualize the number of spaces they prefer, since it is configured in GeneXus.

    Indentation gives developers a better reading of the source code. If we adopt a standard indentation, it makes it easier for everyone else to understand the source code.

    // bad
    if &DocumentType = DocumentTypes.Sale
    msg( "Sale")
    endif
    
    // bad
    if &DocumentType = DocumentTypes.Sale
    		msg( "Sale")
    endif
    
    // good
    if &DocumentType = DocumentTypes.Sale
        msg( "Sale")
    endif

  • 2.2 Indent the conditions and commands inside a for each.

    // bad
    for each
    where DocumentType = DocumentTypes.Sale
    ...
    endfor
    
    // bad
    for each
    defined by ClientName
    ...
    endfor
    
    // good
    for each
        where DocumentType = DocumentTypes.Sale
    
        ...
    endfor

  • 2.3 If a for each specifies a where, defined by, or others, leave a blank line before the code.

    // bad
    for each
       where DocumentType = DocumentTypes.Sale
       if DocumentTotalAmount > MaxCreditAmount
          ...
       endif
    endfor
    
    // bad
    for each
       defined by ClientName
       for each Documents
          ...
       endfor
    endfor
    
    // good
    for each
       where DocumentType = DocumentTypes.Sale
    
       if DocumentTotalAmount > MaxCreditAmount
          ...
       endif
    endfor
    
    // good
    for each
       defined by ClientName
    
       for each Documents
          ...
       endfor
    endfor

  • 2.4 Leave a space before each parameter.

    It makes the sentence easier to read.

    // bad
    parm(in:CountryId,out:&CountryName);
    
    // good
    parm( in:CountryId, out:&CountryName);
    
    // bad
    &Date = ymdtod(2017,01,01)
    
    // good
    &Date = ymdtod( 2017, 01, 01)

Back to Top

Enumerated Domains

  • 3.1 Avoid the use of fixed literals/numbers when there can be multiple values.

    It simplifies reading and removes the need to remember the specific text of each option.

    // bad
    if &HttpResponse = "GET"
    
    // good
    // Create an enumerated domain HTTPMethod with the possible values ( POST, GET)
    if &HttpResponse = HTTPMethod.Get

  • 3.2 Enumerated domains whose value will be stored in the database should be of type CHAR.

    This makes it easier to read the queries the user runs directly against the database. It is preferable to use CHAR(2 to 3) to optimize searches through small indexes.

    // bad
    AccountMovement.Credit 1
    AccountMovement.Debit  2
    
    // good
    AccountMovement.Credit "CRE"
    AccountMovement.Debit  "DEB"

  • 3.3 Avoid defining enumerated domains with "Empty" values (0 or "").

    For example, if we later want to display them in a combo, the "Empty item" will not work.

    // bad
    ReadMode.Normal     ""
    ReadMode.Sequential "S"
    
    // good
    ReadMode.Normal     "N"
    ReadMode.Sequential "S"

Back to Top

Structured Data Types

  • 4.1 Use New() when creating an SDT instead of Clone(). Do it even before using the SDT for the first time rather than at the end (even though GeneXus supports it).

    It makes it clear that we are working with a new item.

    // &Client SDT:Client
    // &Clients list of SDT:Client
    
    // bad
    for each Clients
       &Client.ClientName = ClientName
       &Clients.Add( &Client.Clone())
    endfor
    
    // good
    for each Clients
       &Client = new()
       &Client.ClientName = ClientName
       &Clients.Add( &Client)
    endfor

  • 4.2 Since GeneXus allows defining variables as lists, avoid creating SDTs of the list type.

    When defining the variable of the particular item, mark it as a list.

    // bad
    SDT:Clients : List
    	ClientItem
        	ClientName
    
    // good
    SDT:Client
       	ClientName

Back to Top

Strings

  • 5.1 Use format to display messages that contain data and in calls to javascript functions.

    If the application is going to be translated into different languages, there is no need to re-program the messages.

    // bad
    &Msg = "Client #" + &ClientId.ToString() + " is called " + &ClientName
    
    // good
    &Msg = format( "Client # %1 is called %2", &ClientId.ToString(), &ClientName)

    This solves translation according to context. For example,

    english: "The name of John's dog is Gandalf"
    
    spanish: "El nombre del perro de John es Gandalf"
    

    The above, done through concatenation, would not be translated correctly.

    In the following case, we can see how we can leave only the text inside a jsevent method to be translated.

    // bad
    &Msg = "confirm('Are you sure you want to add an exception?')"
    &LstExc.JSEvent( "onclick", &Msg)
    
    // good
    &Msg = format( !"confirm('%1')", "Are you sure you want to add an exception?")
    &LstExc.JSEvent( "onclick", &Msg)

  • 5.2 Use !"" for strings that must not be translated.

    A translator could modify constants or system-specific codes and affect the behavior, for example parameters.

    // bad
    &ParmVal = ParamGet( "GLOBAL ENCRYPT KEY")
    
    // good
    &ParmVal = ParamGet( !"GLOBAL ENCRYPT KEY")

  • 5.3 Use single quotes by default.

    We do it this way because every event or subroutine created by GeneXus uses single quotes.

    // bad
    &Msg = "Hello world!"
    
    // good
    &Msg = 'Hello world!'

Back to Top

Comments

  • 6.1 Use /** ... */ for multi-line comments in behavior descriptions. You can still use // since GeneXus allows auto-commenting with Ctrl-Q | Ctrl-Shift-Q.

    // bad
    // CreateClient creates a new client
    // based on the variables:
    // &ClientName
    // &ClientAddress
    sub 'CreateClient'
      // ...
    endsub
    
    // good
    /**
     * CreateClient creates a new client
     * based on the variables:
     * &ClientName
     * &ClientAddress
     */
    sub 'CreateClient'
       // ...
    endsub

  • 6.2 Use // for single-line comments. These comments must be on the line before the subject being commented. Leave a blank line before the comment unless it is the first line of the block or you are commenting a where in a for-each.

    // bad
    &ClientName = "John Doe" // Assign the name to the variable
    
    // good
    // Assign the name to the variable
    &ClientName = "John Doe"
    
    // bad
    sub 'CreateClient'
       msg( "Creating client", status)
       // Create the client
       &ClientBC = new()
       &ClientBC.ClientName = "John Doe"
       &ClientBC.Save()
    endsub
    
    // good
    sub 'CreateClient'
       msg( "Creating client", status)
    
       // Create the client
       &ClientBC = new()
       &ClientBC.ClientName = "John Doe"
       &ClientBC.Save()
    endsub
    
    // this is also good
    sub 'CreateClient'
       // Create the client
       &ClientBC = new()
       &ClientBC.ClientName = "John Doe"
       &ClientBC.Save()
    endsub

  • 6.3 Start every comment with a space so they are easy to read.

    // bad
    //Is active
    &IsActive = true
    
    // good
    // Is active
    &IsActive = true
    
    // bad
    /**
     *Get the company name
     *to display it afterwards
     */
    &CompanyName = CompanyNameGet( &CompanyId)
    
    // good
    /**
     * Get the company name
     * to display it afterwards
     */
    &CompanyName = CompanyNameGet( &CompanyId)

  • 6.4 Prefixing comments with FIXME or TODO helps other developers quickly understand whether they are looking at a possible problem that needs to be reviewed or at a suggested solution to an existing problem. These are different from regular comments because they call for action. Those actions are FIXME: -- needs to be solved or TODO: -- needs to be implemented.

  • 6.5 Use // FIXME: to flag problems.

    // FIXME: Check when &Divisor is 0
    &Total = &Dividend / &Divisor

  • 6.6 Use // TODO: to flag implementations to be done.

    // TODO: Implement the subroutine
    sub "CreateClient"
    endsub

Back to Top

Commands and Functions

  • 7.1 Use lowercase when naming system commands and functions.

    This optimizes development since the commands and functions provided by the language are used so frequently that there is no need to write them in PascalCase.

    // bad
    For Each
       Where ClientId = &ClientId
       Msg( ClientName)
    EndFor
    
    // good
    for each
       where ClientId = &ClientId
    
       msg( ClientName)
    endfor
    
    // bad
    &Date = YmdToD( 2017, 01, 01)
    
    // good
    &Date = ymdtod( 2017, 01, 01)

  • 7.2 Use do case whenever possible to replace nested if statements. Leave a space between each case block.

    // bad
    if &DocumentType = DocumentTypes.Sale
       ...
    else
       if &DocumentType = DocumentTypes.Purchase
          ...
       endif
    endif
    
    // also bad
    do case
       case &DocumentType = DocumentTypes.Sale
          ...
       case &DocumentType = DocumentTypes.Purchase
          ...
    
    endcase
    
    // good
    do case
       case &DocumentType = DocumentTypes.Sale
          ...
    
       case &DocumentType = DocumentTypes.Purchase
          ...
    
       otherwise
          ...
    endcase
    
    // also good - When there are multiple cases and the action is a single line.
    > This makes it easier to read all the options without scrolling.
    do case
       case &Action = Action.Update      do 'DoUpdate'
       case &Action = Action.Insert      do 'DoInsert'
       case &Action = Action.Regenerate  do 'DoRegenerate'
       case &Action = Action.Clean       do 'DoClean'
       case &Action = Action.Refresh     do 'DoRefresh'
       case &Action = Action.Reload      do 'DoReload'
       otherwise	do 'UnexpectedAction'
    endcase

  • 7.3 Use the where clause in for each commands instead of "if" statements, whenever dealing with extended table attributes.

    This moves the condition to the DBMS and makes it part of the select query, avoiding working with large volumes of data in the application server or eventually in the client.

    // bad
    for each Documents
       if DocumentType = DocumentTypes.Sales
          ...
       endif
    endfor
    
    // good
    for each
       where DocumentType = DocumentTypes.Sales
       ...
    endfor

  • 7.4 Use "when" in for each commands to simplify the query sent to the DBMS.

    // bad
    for each Documents
       where DocumentType = DocumentTypes.Sales
       where DocumentDate >= &StartDate or null(&StartDate)
       ...
    endfor
    
    // good
    for each
       where DocumentType = DocumentTypes.Sales
       where DocumentDate >= &StartDate when not &StartDate.IsEmpty()
    
       ...
    endfor

  • 7.5 Use the latest syntax whenever the version supports it.

    // bad
    &Name = udp( PNameGet, &Id)
    
    // good
    &Name = PNameGet( &Id )
    
    // bad
    call( PNameSet, &Id, &Name)
    
    // good
    PNameSet( &Id, &Name)
    
    // bad
    &Num = val( &NumChar)
    
    // good
    &Num = &NumChar.ToNumeric()

Back to Top

Parameters

  • 8.1 Use an SDT instead of multiple parameters.

    This is important for objects with several in or out parameters, since reading becomes confusing and, if parameters need to change, all callers must be reviewed. If there are several output parameters, separate SDTs should be created, both for input and for output.

     // bad
     parm( in:&ClientName, in:&ClientLastName, in:&ClientPhone, in:&ClientAddress, in:&ClientDOB);
    
     // good
     parm( in:&sdtClient);
    
     // Web service example
     // bad
     parm( in:&Name, in:&Age, in:&MaritalStatus, out:&Id, out:&ErrorId);
    
     // good
     parm( in:&PersonCreateRequest, out:&PersonCreateResponse);

Back to Top

Subroutines

  • 9.1 When defining subroutines, add the name as a comment on the same line.

This lets us see the subroutine name when they are collapsed.

 // bad
 sub 'CreateClient'
    ...
 endsub

 Result: "+Sub Block"

 // good
 sub 'CreateClient' // Create Client
    ...
 endsub

 Result: "+Sub Block ('Create Client')"

Back to Top

Good Practices

  • 10.1 Version the system as xx.yy.zz.

Where: - xx: Major version changes of the system. It changes no more than once a year and generally implies a major change in the system. - yy: Incorporates database changes. - zz: Incorporates only changes in the binaries.

  • 10.2 Keep the current version of the application inside the binaries.

    This makes it possible to know unambiguously which version of the application we are working with. The version can also be stored as a parameter inside the database, so we can get the difference with the version of the binaries and take the desired action.

    To achieve this, create a procedure that returns the version we are working with:

    // Parameters
    parm( out:&Version)
    
    // Source
    &Version = !"1.05.06"

  • 10.3 Default properties

Isolation level: Read committed
Generate prompt programs: No

  • 10.4 Do not show passwords in logs and debug information.

    This improves the security of the systems, preventing credentials from being left in files and consoles with their potential security risks.

  • 10.5 Set specific namespaces in SDTs used in web services.

    This avoids problems in production if the environment changes its default namespace. It is defined in the "name space" property of the SDT.

  • 10.6 Avoid loading grids by default.

    In most cases the user will apply some filter, and loading by default wastes DBMS resources.

  • 10.7 Consider creating new attributes as "null".

    It helps avoid re-creating the table on a Reorg. Especially on large tables where the data migration time can be too long.

  • 10.8 Avoid accessing sessions (websession) from procedures with business logic.

    Session access should be the responsibility of the interface. Working with sessions inside procedures introduces interface logic into the problem domain. Because of this, we may later have problems if we want to use those procedures in batch or win console executions.

  • 10.9 Do not keep business logic in the interface.

    Following the previous idea, business logic should not be incorporated into the interface. The clearest case on the web is generating Excel exports and reports in web panels. If instead we encapsulate them in procedures, we can eventually generate them from other interfaces.

Back to Top

Resources

Companies that use this guide

This is a list of organizations that are using this development guide. Let us know if your company uses this guide (info@sincrum.com) or a fork of it and we will add you.

Back to Top

Translation

This style guide is also available in other languages:

Back to Top

Collaborators

License

Creative Commons License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

The full text of the license is in the LICENSE file.

based on AirBNB Javascript guide

Back to Top

Amendments

We encourage you to fork this guide and change the rules to fit your team's style guide. Below, you may list some amendments to the style guide. This allows you to periodically update your style guide without having to deal with merge conflicts.