At a client recently I came across a strange problem with a 2007 page layout not working under SharePoint 2010. My troubleshooting uncovered many issues in the environment (with content types and page layout properties), but the root cause of the problem was a bug caused by the misuse of comments.

The page layout had been modified since it’s first draft. The person revising the page had commented out some sections. This is common practice when developing. Even with source control, it is often easier to comment and uncomment sections in place of rolling back an entire file. And it is sometimes useful to have a visual reference of the original  part while working on the changes.

The main problem was that the coder used the wrong type of comment. He (yes, it was a he:) used an HTML comment

<!–    –>

to enclose SharePoint controls. While HTML comments will keep browsers from rendering content, it doesn’t prevent SharePoint from rendering the control, and generating the HTML markup that would go inside the HTML comment markers. This wastes a small amount of server processing and network every time the page is called.

On top of this, Since SharePoint was aware of this control on the page, it adjusted it’s behavior in other ways, which, when combined with the fact that the output of the control was not being rendered by the browser, caused the page to break. The original editor was lucky, since this issue was not exposed in 2007, only 2010.

The correct way to comment part of an ASPX file is

<%–    –%>

Note the percent sign is in the trailing section too. This comment prevents SharePoint from rendering the control, and makes it effectively invisible, not only to the client, but to the server as well.

But in the end this comment should not have been left in the code. After debugging is complete, these remnants of code should be completely removed from the source before being used in production. A source code repository should be used if reference to old code is desired. Comments should only be used to help describe interesting or complex pieces of code, but not to “hide” unused code.