Developer comments

I don't know why anyone would think Developer Comments were not best practice. Commenting code is a must to explain the why and the what of the code when the code in itself is not self-explanatory. The principle is that you should put yourself in the shoes of someone else who is seeing your code for the first time and what they might find useful in order to maintain it. Think what you would like to see if you were looking at some new code for the first time and then leave the comments you'd like to see.

As long as we are on the subject of comments, is there a way to make a single line comment?

I.E., I know we can use /**/ to do comments, which I would refer to multiline comments, but is there a single line comment text, like -- in PL/SQL?

Not AFAIK in the way you're describing...putting /* a comment */ on a single line works of course!

This is what I was expecting you to say, but when I searched Appian documentation I found nothing on even how to do the  /**/ method of comments.

I'm not sure what you mean by "how to do"?  You put "/*" at the start of the desired comment, and "*/" at the end.  This works for single-line as well as multi-line comments.

In the Expression/Interface editors, you can also use the keyboard shortcut CTRL+/ ("control & forward slash"), as noted in the editor itself, to instantly comment / un-comment the current row.  Additionally you can press CTRL+Shift+/ to comment the currently selected text.

In PL/SQL (and some other languages) you can make comments two ways.

Multiline comments:

/*  This is how you do a multiline comment

You can put a whole paragraph here, or more!*/

-- This is a single line comment.  You can also place this after some code in the same line with it.

More examples here:

www.oracletutorial.com/.../

I swear Appian must have no database developers working there!

I recall seeing an issue where lengthy comments actually impacted interface performance. Maybe that drove this perception? Probably resolved by now, though.

The only difference is Appian doesn't have a separate operator for single line comments like "--" or "//"  ... you just use /* ... */   - honestly, it's not that hard.

Part of our best practices are to use comments to add JIRA story numbers, the name of developer, and changes made to the top of the code file, and then another comment adjacent to changed code to keep a rolling change log within Appian code objects, specifically SAIL interfaces and Expression Rules.

We also have a large annotation field on each PM which also serves as a change log.

Self-commenting code is a myth designed to make people feel good about not commenting their code.  You should have clean elegant code with meaningful variable names such that you don't need to comment what a particular piece of logic does, but you still comment WHY you're doing it or even WHY you're doing it this way.

e.g. I see when there's anything after the third decimal place, you always round up, but WHY do you always round up?  Because this module is for converting foreign currency into USD, and we need to make sure we always have AT LEAST enough USD down to the cent to cover the full amount of all the foreign currency.  We'd rather overpay by up to a penny than not have enough.

This was part of the standard practice we had in place when I was a Mainframe COBOL developer: a 'Header' section that contained details of the Author/Developer of the code and any subsequent changes, along with the relevant Change Reference so that there was traceability of code changes to authorise requirements. And then, inline with the code, anything that needed to be called out to explain the what and/or the why, whatever it takes to reduce the friction that comes with changing someone else's code.