SQL tutorial •
Tips & Tricks

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 <span class="code">--</span> and <span class="code">/*</span> to add comments to your code. <span class="code">--</span> works for single line comments, meaning that if you add <span class="code">--</span> to a line of code, everything after <span class="code">--</span> 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 <span class="code">/*</span> and ending with <span class="code">/*</span>. Everything in between <span class="code">/*</span> and <span class="code">/*</span> will be ignored in the query, so it can be used for writing several lines of comments.

Next up: