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.
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.
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.
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.
I’m going to disagree with the disagreers and all manner of “commenting” suggestions.
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 require no special markup.
Annotations can easily realign themselves with native functions even if they move within a formula.
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 it – commenting. 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.
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.
@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!
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.
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.
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.
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!