Amen

nkadonaga · 03-08-2021 12:50 PM

Hey everyone! We just started rolling out the ability to add descriptions to expressions. We’re starting with just slice filters, but we plan to expand the supported locations in the editor as we develop the feature.

As the rollout progresses and you’re able to try it out, we would love to hear your feedback and thoughts in this thread!

Note: If you’ve opted in early to the “Use words to create expressions” feature, the “descriptions” feature is already available to you.

FAQ

Why add this “descriptions” feature?

App creators won’t have to click into the Expression Assistant to understand the expression, especially when the expression has been visibly truncated in the slice definition.
Descriptions may help app creators to remember what their formula does.
On apps with multiple app creators, descriptions may make collaboration easier, as it allows the expression author to explain their intent.
Descriptions allow AppSheet to use these descriptions as training data for machine learning models that enable app creators to “use words to create expressions.”

What’s the difference between this and the “Descriptive comment” field for the slice?

Descriptive comment: Any generic description about the slice
Expression description: Declarative description about what the slice filter expression does

I realize this can be confusing, so any feedback on ways to disambiguate these fields is appreciated.

If I’m not interested, how do I opt-out?

For now, opt-out is not available for self-service and must be done manually, so to do that, you can send me a PM with your account ID. I will add a self-service option in due time.

Austin

Everywhere. Every Expression. Please.

GreenFlux

Hey @natalie , thanks for the update! This is definitely better than having no comments at all, and seems like a good alternative to completely rebuilding the expression engine to support true //comment lines. I’d prefer to be able to insert comment lines anywhere in the expression, but I realize what a massive overhaul that would require.

Would it be possible to select both in an array when copying, and then parse them back into separate descriptions & expressions when copying/pasting between columns? That way, even though they ‘live’ in different fields of the editor, they could be easily ported from one column to another and ‘travel together’ to save us an extra round of copy/paste.

kambwili

This is great! I’m especially excited to see this feature attached to all expressions.

WillowMobileSys

I won’t use them but I think it’s great that others have the option.

The only thing I ask is that example descriptions are not automatically inserted like they are for “Related” Virtual Columns. It is tedious to remove them. Why do I remove them? Text is one of the slowest things to load/transmit - even when loading the app in the editor. I don’t need the descriptions and comments so I remove as much of them as I can to help with app load time. Does it make a huge difference? Maybe not but I try to give myself every edge that I can as I work in several apps every day.

By the way, descriptions and comments are only good if they are kept up to date. If you use them, be diligent in keeping them updated - otherwise they are worthless.

Austin

Let me be happy even though I know 2 changes later on my formulas I’m not gonna remember to update the description

MultiTech

Amen

elco

Many of us like to follow the “Good Practice” even though it makes our lives harder. There is a certain sense of satisfaction when you reach that 100% test coverage, or document your code thoroughly.

This is amazing feature, specially because it’s not at all easy to understand and existing AppSheet app; as it is 2 steps removed from the reasoning. It’s much easier if you can have the source code due to IDE’s code analysis tools.

I’ve loved to use the documentation section for every table, view, slice I created. I always wondered how/who/where you can read all these docs, still I did my duty for myself.

Stefan_QREW

Super cool! I think this is a really savvy feature

David_Ackling-J

This is VITAL and I am urgently needing this to be implemented everywhere in appsheet. I’ve built our entire organisation on a single Appsheet app. Starting 4 years ago when it was just me. Now there’s over 70 users. We have developers seeking to refactor the app. The lack of commenting on expressions has been a massive problem. Thanks for rolling this out urgently.

Kirk_Masden

Will the text of the description be included in the “application documentation” that is created for each app?

I find it convenient to search the text of this document to find thing in my rather large app. I hope the text is included.

nkadonaga

Thanks everyone for the responses! I’ve answered them below. Apologies for the delay.

Thanks for sharing that feedback. It is not possible, but I’ve added this request to our internal tracking system for further consideration.

If the expression was authored using your own words (via the feature in Use words to create slice filter expressions), the Expression Assistant will use the words used to “search” the suggestions as the default description. This behavior is shown below:

Otherwise, we do not automatically insert descriptions.

Good point, I’ve added this to our internal tracking system as something we could try to solve – possibly by introducing some visual indication that the description is “stale” with respect to the expression.

It isn’t currently supported, but I agree we should – added this request to our internal tracking system.

WillowMobileSys

Hi Natalie, while this comment was mainly aimed at the community who wanted the ability to notate their expressions, I suppose it also applies to us all for anything we do.

Add descriptions to expressions

Amen