Accepting our shortcomings is a pre-requisite for an improvement

In the initial days of my professional career, I joined a project as a Software Engineer. Once I got access to the codebase, I started going through the codebase. The project was using JSP technology for the views (server-rendered views).

A senior developer from the team was demonstrating the implementation of one of the features of the application. He opened a particular JSP file, which was part of the workflow. I noticed something interesting. There were some comments meant to help the developers understand the code.

(Whether the comment was of any help is a different question, and I will discuss that another time!)

I observed that the comment was an HTML comment, not a JSP comment.

An HTML will be passed on to the generated HTML, while a JSP comment will only be available in the JSP file and not present in the generated HTML.

Here is a sample HTML comment

<!-- HTML comment -->

This is how a JSP comment would look like

<%-- JSP comment --%>

I asked him, "Why did we use an HTML comment here instead of a JSP comment?". Another senior person from the team who was in the meeting responded, "Don't worry. The users of the application are not very technical and will not use the 'view source' feature of the browser to see the HTML code." Maybe it was a sudden reaction as he might not have expected this question from one of the junior most developers.

The idea here is not to blame the individuals involved but to learn from our experiences and respond in a better way in the future.

Let us analyse the trade-offs between HTML comments and JSP comments.

• The cost of creating - Both would take about the same time to write, hence no difference in the cost.
• Impact on bandwidth - HTML comment would use marginally more bandwidth
• Security - The comment may give the user additional information on the implementation technology, which might make it easy to create security attacks. (In this case, though, all the users were employees of the customer)

JSP comments should be the default choice here. There is no additional cost to opt for them, and they offer benefits over HTML comments.

I understand that an oversight of the developer might have caused this. However, the bigger question is whether the team has a culture that welcomes improvement ideas from every team member. Also, we will only get an improvement idea if one of us decides to pay close attention to even the smallest part of the system we work with.

Suppose we work on a project/ product for a year. We would have had the least knowledge about the system on day one and the highest knowledge at the end of the year. Hence, when we look at our past work, we can obviously see some scope for improvement. Accepting this fact would positively impact the system we work with and help us learn and improve our skills.

Thus, welcoming any opportunity that would reveal our shortcomings would, in turn, open the doors for improvement.