diff --git a/site/source/docs/optimizing/Optimizing-Code.rst b/site/source/docs/optimizing/Optimizing-Code.rst index 5f09aa9e3119..97f1ba86547f 100644 --- a/site/source/docs/optimizing/Optimizing-Code.rst +++ b/site/source/docs/optimizing/Optimizing-Code.rst @@ -4,7 +4,18 @@ Optimizing Code =============== -Generally you should first compile and run your code without optimizations (the default). Once you are sure that the code runs correctly, you can use the techniques in this article to make it load and run faster. +Generally you should first compile and run your code without optimizations, +which is the default when you just run ``emcc`` without specifying an +optimization level. Such unoptimized builds contain some checks and assertions +that can be very helpful in making sure that your code runs correctly. Once it +does, it is highly recommended to optimize the builds that you ship, for +several reasons: First, optimized builds are much smaller and faster, so they +load quickly and run more smoothly, and second, **un**-optimized builds contain +debug information such as the names of files and functions, code comments in +JavaScript, etc. (which aside from increasing size may also contain things you +do not want to ship to your users). + +The rest of this page explains how to optimize your code. How to optimize code ====================