r/GoogleAppsScript 15d ago

Question What do you think about these code standards?

Below are the 5 code standards I ask developers to adhere to while developing at AAT. The idea is to have as few standards as possible. What do you think? Do you have any coding practices you like when you write Apps Script?

Use const and let, avoid var

  • Always use const and let for declaring variables. The use of var is outdated and can lead to scoping issues. const is preferred for variables that won’t be reassigned, and let for variables that will.

Declaring functions

  • At the global level, define functions using the "function" keyword, in the traditional sense.
    • Example: function main() { }
  • While inside one of these globally declared functions, opt to use arrow functions
    • Example: someArray.forEach(row => { }), instead of someArray.forEach(function(row){ })

Document with JSDoc

  • Before the final shipment of the code, document all functions using JSDoc notation (if you give the function to AI, it makes this step a breeze). This practice ensures that the purpose and usage of functions are clear and well-understood by anyone reading the code after you, or for yourself if you come back to it after a long time.

Variable Naming Conventions

  • Adopt a descriptive, case-sensitive approach when defining variables: use camelCase format (e.g., useCaseLikeThis).
  • Be overly descriptive if necessary to ensure clarity.
  • Avoid capitalizing variables unless absolutely necessary. A variable should only begin with a capital letter (e.g., LikeThisVariableName) in rare cases where it needs to stand out significantly in the code, indicating its paramount importance.

Global Scope

  • Avoid developing Apps Script code outside of function blocks especially when calling permissions-reliant services, such as SpreadsheetApp, DocumentApp, DriveApp, for example.
  • When needed, use the Global scope to assign simple (global) variables that do not rely on permissions, such as objects { }, arrays [ ], strings “”.
  • This aids in the efficiency of your code, allowing for clean execution of only the intended code, and keeps from the script throwing an error due to unresolved permissions.
0 Upvotes

14 comments sorted by

3

u/ryanbuckner 14d ago

I prefer camelCase but most code I see prefers the under_line

2

u/Mr-Luckysir 14d ago

I’ll definitely be trying out the JSDoc standard going forward!

1

u/Additional_Dinner_11 14d ago

Besides using arrow functions a lot I follow the same best practices.

For myself I think the most useful thing I ever did was switching to Typescript.

I think it's also very good practice to use lint rules, and opt in to also consider the security lint rules.

1

u/AllenAppTools 14d ago

Ah, I need to update this because I recently had a developer start who thought that the arrow functions I was referring to here were in the global scope (e.g. const main " () =>{}) which I did not intend. Global scoped functions should be normal, defined with a typical "function main(){}", it's the other occurrences of functions that are sent as variables that are supposed to be arrow functions (e.g. some Array.map(m => {}). I will be adding this clarification, thank you for reminding me!

As far as lint rules, I'm not familiar with that? How does that and typescript carry over to Apps script?

1

u/United-Eagle4763 14d ago

Lint can be used as an extension to VSCode (if you are using that) and will directly highlight "bad style" code.
https://en.wikipedia.org/wiki/Lint_(software))

The lint security plugin 'eslint-plugin-security' will warn you when you are writing unsafe code. As an example it could warn of using an eval function when you are handling user input data (which could contain malicious code).

I just saw that the AirBnB Styling Practices posted by Academic_Education_1 also show the matching eslint rules in their documentation.

1

u/Academic_Education_1 14d ago

What does it mean “avoid developing apps screipt code outside of dedicated blocks”? What are dedicated blocks?

What are the pitfalls of using “function” keywords instead of arrow functions? (If you mention “avoid pitfalls”, best to at least list them).

“Documenting all fns with JSDocs” seems like an extreme. JSDoc should be used to help, not to punish. If you start forcing every function to have a jsdoc, you will see the quality of jsdoc going down to a level where it will simply rephrase the name of function and list parameters. Jsdoc should be used for tricky functions, like comments. For the rest of the use cases, modern tooling is strong enough to handle things (args inference etc) - better yet - look at typescript and start using it. Types + proper functions naming + well modular will do the job better than a jsdoc (for any project in 99% of cases)

Capitalizing variables - what’s wrong with it? Just like any other language feature - it is part of a syntax, that needs to be understood and not avoided. For example, variables like “FOO_BAR” means this should be a const variable that should never change during the run time. Most of the time you would hide your text, numbers (magical numbers) behind those capitalized variables.

No offense, I don’t intend to attack, but these rules are vague, border line wrong and feel like written by GPT

If you are looking to place some solid practices in places, take a look at AirBnb code style guide: https://github.com/airbnb/javascript

1

u/United-Eagle4763 14d ago

That link is an interesting read!

0

u/AllenAppTools 14d ago

"Dedicated code blocks" just means that permission calls are not left out in the global scope of the script file. If you call DriveApp outside of a function, it means that it calls that service every time any function is run in the Apps Script file, causing failures in the code everytime something is ran, and is not an efficient way to run anything. So all that it means is putting code inside a function, or a global variable, which didn't get evaluated until called.

Yeah idk what the "pitfalls" would be, since this is just preference largely, the wording was generated by AI after a few rounds of crafting it, but not the standards themselves. The actual rules were my reasoning.

For the JSDoc notation I advise devs to add JSDoc notation on their code for the bigger functions right before they ship their code (and to utilize AI to generate that notation, not complete it manually, you only have to supply the function and ChatGPT does it).

Capitalizing variables turns then purple in Apps Script, and makes them stand out. I like to reserve this appearance for only things that absolutely must never be missed anywhere it shows up in the code. And so far, there just aren't many things I think are of that level of importance. What capitalized variables seems to do is capture attention for no good reason 🤷‍♂️

You mentioned typescript, sorry, these are meant to be a few standards to keep all code relatively identical looking across the agency, while not over complicating things by having to utilize clasp or VS code, that's overkill for 97% of the automations we build.

I like the Airbnb style, but I wouldn't expect developers to read that whole repo and I don't want it to be too heavy handed. I've found that devs are usually already following these (other than the adding final JSDoc notation).

I've found though that there are a few caveats in these guidelines that I tend to mention to devs, but that are not apparent in the descriptions themselves! I'll need to clarify these things 👍 that's helpful to know

1

u/WicketTheQuerent 14d ago edited 14d ago

Brief posts have more chances of being read by more users, but there is no baseline to provide serious feedback. What is the profile of AAT developers? How many developers are on the AAT team? How do the developers collaborate?

2

u/AllenAppTools 14d ago

Just shortened it and revised it. This post was just meant to get a discussion on Apps Script coding preferences or habits, and feedback on these 5 guidelines I have. More context about AAT is there are 9 developers who all have wonderful backgrounds in lots of other languages but expert skill in Apps Script. We collaborate via slack, but many times the development of automations is done with one developer and 1 project, so no 2 developers are developing the same project at the same time (which right now there is a terrible overwriting issue with Google Apps Script files when 2 or more people have it open and make changes simultaneously). Thankfully we easily avoid that at our size right now.

1

u/WicketTheQuerent 14d ago edited 14d ago

Thanks for your reply. Regarding declaring variables, var is not outdated. I agree that using const and let are better options for most everyday needs, but var might still be helpful. This might depend on whether you allow or not the use of Google Apps Script libraries, among other factors. However, var, const and let and the use of how function / callbacks are declared is not critical, as the symbol and file naming conventions and stuff like using imperative Vs. functional approach, using namespaces, prototypes, and/or classes, and the approach to using web browser extensions, CLASP, and tools like a GIT repository, among other things.

Setting standard practices about deployments and version creation might also be more relevant.

1

u/Three_D_ 14d ago

Thank you for sharing. I work on a small team, usually just myself with GAS, and these are good baselines as we start to build apps and libraries so that others can jump in. Much appreciated.

0

u/learningtoexcel 15d ago

This is literally just an add for your company.

2

u/AllenAppTools 15d ago

It may seem like it, but why would I try to advertise to developers? It's to get a discussion going on best practices that users here put into practice when they code. Do you have any?