Comments are useful for maintaining software, but end users should not see them.  They can also reveal information about possible security flaws, so extra care must be taken to ensure comments stay hidden from view.

For example, the traditional way to do HTML comments is below

    BUG: This page still grants access if the  
         user changes date on their PC to before 2000.   
         Michael to fix.

But the above comment will be seen by anyone who views the HTML source of the web page, clearly not what the developer had in mind to show to customers or potential hackers.  If correct JSP comment tags are used, the text is stripped out when the page is compiled:

This will be removed by the JSP compiler
     and never sent to the browser.

Style sheet and javascript comments are generally required for maintainability of the software, and these cannot be easily hidden.  So in .css and .js files, don't give too much information about your architecture, and keep in mind that everyone can read them.

Tip: One school of thought says that you should not include any comments in the final HTML at all.  It gives information to potential hackers about your flaws and processes which may lead to a back-door into your software.  The less information they have the better, so strip out all comments at compile time using the <%-- --%> tags.  It's a little harder to do this in Javascript, so don't leave anything that may be exploited in it, like usernames, passwords, or secret URLs.

blog comments powered by Disqus