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.
Documentation in Weld Editor
The Weld editor has a built-in documentation feature. This is great for explaining both:
- 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)
- Technical model documentation (what’s being done technically and which choices have been made).
Adding Comments in SQL Code
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.
How to Add Comments in SQL
- You can use
--and/*to add comments to your code. --works for single line comments, meaning that 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 here
2 column_a
3 , s.column_b
4 , o.table_c_id -- 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
10 Here, Here
11 , And here */