Comments within code

[SBSA_DW2]

Hi guys

I was asked today if it was possible to comment within a constraint or derivation. The answer is of course no, but wouldn't it be nice to have /*comments inside the constraint or derivation */?

How are you guys going about documenting complex derivations/constraints at the moment? Is the annotation stage the best bet?

At the moment annotations and a good dose of documentation inside the job properties "full job description" is where it's happening for us.

Interested in hearing your thoughts.

cheers

[PhilHibbs]

There doesn't seem to be any place inside a transformer to put a comment. You could add a Stage Variable and set it to a literal string with your comment in it, but that assignment is going to be executed for every row of data. Annotations are good, and can be colour-coded for user action such as reports to be retrieved, row counts that must be zero, etc.

[chulett]

All stages have a General tab which is a perfectly good place for comments, even though some people may overlook them there. Stage Variables have a Description field in their setup screen where I always document their function.

But no, as noted, there's no place for comments in code / derivations or where they would be visible with the Editor open. Other than Annotations on the canvas, of course.

[PhilHibbs]

Stage Variables have a Description field in their setup screen where I always document their function.

The problem with that is that if people are unaware of them, then they will not be maintained. An out-of-date, misleading comment is worse than no comment at all.

↓ dn ʎɐʍ sıɥʇ

[chulett]

Of course. That's where Standards come in. Mostly. The rest is handled with a Big Stick.

[PhilHibbs]

Of course. That's where Standards come in. Mostly. The rest is handled with a Big Stick.

I should add the description field to my analysis spreadsheet, then you could tell at a glance how many people are filling them in - if people are entering them in their own code, there is a better chance that they are maintaining them. We don't use the Description, but maybe we should.

[ray.wurlod]

You can (should) document stage variables on the initialization grid.

You can document column derivations in the Description column of the Columns grid, which is a multi-line control (use Ctrl-Enter to move to extra lines).

[PhilHibbs]

You can document column derivations in the Description column of the Columns grid

The what? Is that a Parallel-only thing, or am I missing something?
*Update*: Found it - that's column metadata, not part of the stage. We don't edit our column metadata. It's the description of the Column, not the description of the Derivation.

[ray.wurlod]

But, within the job design, it can be both. I do keep the column description, but add any description of the derivation and any business metadata that ought to be referred to. This does not invalidate the relationship between the link metadata and the table definition in the repository.

[PhilHibbs]

Also there's no visual correlation between the derivation and the column description, so as a place to put a comment it's not that useful. It's like commenting your code in a different file. It's documentation, which isn't a bad thing, but I wouldn't classify it as a comment. Do you routinely look at the Description in the Columns tab when you are looking at Derivations? You even have to double-click on them to get past what I assume is the metadata Description that would show up as the first line. And you can't see more than one line at a time!

Going by my earlier principle that if people don't see it then they won't update it and thus is will become out of date and misleading, this is a terrible place to put comments.