Have you ever seen the d3 javascript visualisation examples? The author has a physics background, so the code ends up being very verbose with lots of comments about simple programming stuff, yet incredibly terse when it comes to heavy mathematics. I would have done the opposite.

It made me realize that people naturally want to be more verbose when they are less comfortable with the concepts and less verbose when they are very familiar with the concepts. It also made me realize it is totally subjective and there may not be a right answer, that it depends on someone's background and familiarities.