Documenting your code

It is highly recommended to document your code properly. This ensures that you and others can go back and understand what the code is doing, how it’s structured in different steps, and why certain choices were made.

Good documentation can save a serious amount of time in the future and avoid issues with the code or potential double work if others don’t understand what you’ve done and decide to start over.

There’s a built-in documentation feature in the Weld editor, which is really good for documenting what the model is doing both in terms of a commercial definition (which metrics are being calculated and what relevance it has to the business) and technical model documentation (what’s being done technically and which choices have been made).

On top of this, it can be very beneficial to add short comments directly in your SQL code. This can be a short comment about what’s happening in each step of the code to make it easier for outsiders to understand — or for yourself in the future.

You can use -- and /* to add comments to your code. -- works for single line comments, meaning that if you add -- to a line of code, everything after -- will be ignored in the query, so you can use it to write a short comment. Several lines of comments can be added by starting with /* and ending with /*. Everything in between /* and /* will be ignored in the query, so it can be used for writing several lines of comments.

1select -- A single line of comment heres. 
2    column a
3  , S.column b.o.table c id
4    -- Another single line of comment here 
5    some_numeric_column
6from
7    some data as s
8    left join some other data as o on s.column_a = o.column _d
9    /* Here are several lines of comments Here 
10  , Here 
11  , … And here */