So…a colleague of mine, posted a tweet today about self commenting code. I briefly replied, along with others, and I thought I’d share some of my thoughts on “self commenting” code and standards.

Whose rules are you following?

First things first, who defines what is self commenting code? I guarantee you that different developers will see code and comments differently. For example, a php developer who is used to a rather loose language structure, will think differently from a more structured C developer when it comes to commenting their code.

There are different interpretations based on different standards, and one such standard I have researched and written about is the Construx CxOne standard based on Steve McConnell’s work. And even by using such a standard as guidance, some of the standard is specific, for example naming conventions and formatting of variables, while other parts are vague, for example in section 1.6 under commenting “Remember the comment audience”

With that said, let’s take this one step further…

Developer Career Levels

If you have been coding for 10 years (or even 5), think back 5 years and ask yourself if you know more or less than what you do now? That’s fairly simple, however, ask yourself if you are a better developer?  Who defines what “better” is – is it a feeling or do you use a metric such as a standard to govern this? Or is it your practices and habits (such as commenting and naming conventions)?

But all that aside, simply think of working in a team with junior and senior developers. I’ve had this very experience at a previous job where one of the senior developers and I had to work together on a project, and he had his ways and I had mine – whose way is better?

But is that even the right question? The real question is, when it comes to coding together is communication. Can I communicate effectively through my code to other developers. If the senior developer on the above project used super complex code with no comments, I would have been screwed and the project would have suffered. But we had defined coding standards before the project began so we knew what to expect. The same should be seen in the WordPress community, as WordPress has set code standards.

Let’s go a bit further down the rabbit hole…

Code Frameworks

Some frameworks use camel casing (but is that upper or lower camel casing…) for naming conventions of variables and functions, some have coding patterns like MVC, MVP, or n-tier, and some use docblocks to generate API docs to elaborate on there instead of the code – and here again it’s worth noting who is the audience? WordPress is a fantastic example of this – the Codex serves the community far better, in my opinion, than tons of comments in the code.

Onwards to my final point…

Who cares?

Ultimately this argument is subjective and people will inevitably have an opinion one way or another, because people are different and like to have their own opinion (just take religious arguments as one example) – the main thing here is to communicate well, if you do that well through your code, then you’ve already won!