Developer comments

RE: Developer comments

Chris — Tue, 13 Jul 2021 16:38:08 GMT

I felt like this deserved it's own Feature Request thread.. Fingers crossed 😬

RE: Developer comments

Mike Schmitt — Tue, 13 Jul 2021 14:43:37 GMT

Agreed, this would be a place where the "//" or "--" comment functionality would be great.

RE: Developer comments

Søren Juul — Tue, 13 Jul 2021 14:41:07 GMT

The problem with commenting out large sections of code, already containing comments, could also be solved by allowing nested comments. For instance this should be possible:

/*

list2: if(
isnull(ri!sortValues), /* sortValues is optional */
ri!list,
ri!sortValues
),

*/

RE: Developer comments

Mike Schmitt — Fri, 21 Aug 2020 18:04:00 GMT

I agree, having "//" would be nice. Especially if the hotkey-comment functionality is updated to ignore it when appropriate.

RE: Developer comments

Chris — Fri, 21 Aug 2020 16:44:21 GMT

I would like to add my sentiments on single line commenting (separate from block commenting), this would be a VERY useful feature to include in the base product!

Primarily in development of complex forms, very often large sections of code need to be commented out in debugging to narrow the target. I can't say how many times I've ctrl+/ uncommented a large section of code only to have all the developer notes uncommented as well, creating a hassle to quickly locate an issue when you have to re-comment these lines prior to continuing work. Or, how many times I've collapsed a large layout section and added /* prior and */ after, only to have the lines partially commented when the first set of dev notes trailing "*/" ends the block-comment I was trying to add..

This hassle would be resolved if we could single-line comment with "--" or "//" as in other languages such as SQL, as these will not conflict when block commenting anything surrounding dev comments.

/*
select 1
--comment!
select 2
*/

Probably my only complaint with SAIL however (except the ability to retrieve the current browser URL would be nice as well ;) ).

RE: Developer comments

Stewart Burchell — Wed, 19 Aug 2020 14:50:15 GMT

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.

RE: Developer comments

davel001150 — Wed, 19 Aug 2020 14:07:47 GMT

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.

RE: Developer comments

Mike Schmitt — Tue, 18 Aug 2020 17:24:44 GMT

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.

RE: Developer comments

Josh — Tue, 18 Aug 2020 16:59:33 GMT

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

RE: Developer comments

scottz0001 — Tue, 18 Aug 2020 15:46:48 GMT

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!

RE: Developer comments

Mike Schmitt — Tue, 18 Aug 2020 15:38:33 GMT

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.

RE: Developer comments

scottz0001 — Tue, 18 Aug 2020 14:16:31 GMT

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.

RE: Developer comments

Stewart Burchell — Tue, 18 Aug 2020 14:04:06 GMT

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

RE: Developer comments

scottz0001 — Tue, 18 Aug 2020 13:56:33 GMT

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?

RE: Developer comments

Stewart Burchell — Thu, 13 Aug 2020 16:05:16 GMT

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.