Ability to make comments in formulas

I am developing tools within Coda with others that require some reasonably complex formulas on columns/ in buttons / in general.

I have some experience coding in other languages, and utilize //comments quite frequently.

I would love to be able to comment like this within formulas to make things a little easier to parse at a glance for myself and others looking at formulas!

For example, in JavaScript you can make a comment using “//”

5 Likes

yes please! I would like this as well

1 Like

A good idea! I agree as well

1 Like

I feel like the catch here, is that Coda’s formulas aren’t really multi-line (they added line breaks but the parsing still seems to be treated as if the whole thing was a single line). In that scheme where does the comment end? You could use <* and *> or something, but it still seems a little unwieldy.

Interested to see what the final solution could be though.

1 Like

Hm yes that is a good point. It seems like a simple addition from the outside, but if it’s all parsed as a single line it undoubtedly is be probably more complex to add as a feature.

I suppose it may be a better practice for me to simply create documentation around the formulas I’m making. It just takes more effort to do that, and to ensure others do that as well😂

One thing you can do in some instances, is to break the formulas down into multiple columns/formulas. Sometimes you can get an intermediate representation of your data in one hidden column, then finish processing the data in a visible column. You can have several hidden columns building up to the final presented output, and each can be a bite-sized process that is easy to parse and understand.

A similar method for canvas formulas is to have intermediate formulas, perhaps on hidden pages, that you reference in your final formula.

2 Likes

In HTML you have always had to close comments:
<!- - comment - ->
I really don’t think it will be hard to get used to something similar and, as far as I am concerned, that would look fine, in particular when you have multi line comments or code you need to comment out.

1 Like

I would like to disagree on that approach, although it is a matter of taste and it can, initially, help to build or debug complex code.

But at the same time, it makes it harder to grasp the overall picture, making changes later on becomes more complicated and moving or copying code becomes very cumbersome.

Even with the cfl editor not being ideal (specifically not wide enough), it does allow for indenting and blank lines. With some care you can write very readable code that is relatively easy to understand for 3rd parties.

And yes, comments would really help. I can’t imagine that a comment function that is not parsed at runtime is all that complicated, so I patiently wait for the day this ‘function’ will be announced.

2 Likes
2 Likes

Um, have you actually tried this in a real formula? I don’t see it working.

I’m going to disagree with the disagreers and all manner of “commenting” suggestions. :wink:

In the interest of a no-code positioning commitment, I urge the Codans to not drag in antiquated commenting support from decades ago. Rather, consider these three very powerful words.

Annotations

  1. Annotations require no special markup.
  2. Annotations can easily realign themselves with native functions even if they move within a formula.
  3. Annotations are meta; they provide vectors into your “code” that may allow search of formula objects with precision as well as identifying similar or related formulas.

Coda already has the infrastructure to support annotations; it’s called – wait for itcommenting. It should also leverage an AI enhancement that makes it possible to write a comment descriptive of the formula’s objective leaving the Maker to watch as it writes the solution.

Sidebar: Ideally, Hypothesis.is would work in Coda, but it doesn’t. I think there’s an issue with the event handlers on the canvas. Otherwise, I would use that to annotate the crap out of my formulas.

3 Likes

Hey @Bill_French
Just like it took a little time to get used to ‘no-code coding’, I will happily adapt to whichever system of commenting fits best with Coda. I am not particularly in favor of using my suggestion, although I would think that can be implemented just like any other new function. But I like your suggestion to implement annotations/comments or something like Hypotheses.is - so let’s hope @coda_hq will implement at least something one of these days.

3 Likes

Thank you for the discussion, all :slightly_smiling_face:

@Bill_French It would be great to be able to use the commenting feature within formulas, and makes a lot of sense in terms of aligning with “no-code” principals. I was thinking about this as I was reading through the thread, about how I have often updated code, and not updated the “//” comments within said code, creating even more confusion.

I am not much of a programmer but I have worked in roles where I have had to try and parse other people’s scripts, and the idea of being able to comment on a specific line sounds very helpful.

I am still relatively new to Coda, so I appreciate hearing these different perspectives!

1 Like

Yes you are. We’re all programmers; simply different shades of developers with skill, experience, and focus. The world runs on programs, and with no/low-code platforms, we have a much broader definition of the term.

This is a slice of the technical debt issue. It’s one thing to cut corners in code and yet another to fix the corner you cut, but leave the comments as before. This is where AI has really changed my world as an accountant-turned-programmer. In tools like VSCode (with CoPilot), the editor is able to look at a modified function and generate an updated comment describing what it does. It is also able to take a comment and generate the code. Lastly, you can take some hastily authored code and ask CoPilot to rewrite it for performance or better clarity.

Coda’s editors and commenting should work in similar ways and I think this reality is not too far off.

2 Likes

Coda Please add this feature.
Some of the formulas gets kind of long and tedious, and difficult to read and understand after a little while, simply because there are no way of adding simple comments to our code.

A simple // or /* */ just like in javascript would be perfect.

1 Like

:wave: Hi! I’m Arpan, a software engineer at Coda. Thanks for sharing this feedback - the good news is that you can now add comments to formulas! By enclosing parts of your formulas with /* and */, that portion will become a comment. Alternatively, you can comment out an entire line by prefixing the line with //.

Formula comments can help explain what’s going on in your most complicated formulas and can also be used to save prior versions of formulas you’d like to refer back to.

2-21-23 Formula comments_2.gif

10 Likes

Hey Arpan, thank you! This is awesome! :partying_face:

Thank you for this @Bill_French - I definitely have a sense of imposter syndrome! I’m glad to be able to develop my skillset using tools like Coda, and to engage with others of varying backgrounds in the world of tech in forums like this. It’s cool to see how people are using Coda in so many different ways.

This is amazing, and very much where things seem to be heading. I watched the Coda AI sneak peek video and it was really interesting. I’m curious to see how this unfolds as these capabilities become more accessible.

Simultaneously, it does seem the request for code comments has been granted, (thanks again @Arpan_Laha!)

I realise now that “comments” may not be the best phrase to use at this point in time, and that maybe its more like “notes” or “inside documentation”, since comments nowadays are usually about communicating with others, and tend to have the goal of being resolved. I find when I comment in code I am trying to leave an “explainer” for my future self and/or others that may come across the code at a later point.

Anyhow, I digress - I will continue on and aim to keep my comments tidy regardless!

1 Like

Thank you for adding this feature!

Dear @Arpan_Laha ,

Now that we have a way of making comments in the editor (thank you so much!!!), I hope there is room for a couple more changes. On my wish list for the expanded editor:

  • flexible size (height and width adjustable with memory for the last used size?)
  • free floating editor (with memory for the last used position?)
  • keyboard shortcut for activating the “done” button
  • a few improvements for autoformat: keep datapairs together (among others in modifyrow() or Swichif())
  • user definable setting to always open the expanded editor and bypass the small editor)

Greetings, Joost

4 Likes