/** Still no comment */

Cedric takes exception to my earlier post another who didn’t get what I was saying. I think that says a lot for my ability to explain ideas, uh?

Let me summarise my response like this:

• I’m deadly serious
• I’m not saying that code should be obscure. I’m saying that comments don’t make it less obscure.
• The aim of the game should be to write code that isn’t obscure.

To reply to Cedric’s points in detail:

The simple truth is: you don’t make junior people become senior by forcing them to understand the intricacies of your coding style. I am hoping that when robertdw gets to read the uncommented code written by these junior people and he tries to make sense of it, he will start realizing the importance of thoughtful, well-written comments.

Cedric, I invite you to read the next post I made on the levels of code quality. I’m not disputing that junior developers write bad code; that’s a consequence of their inexperience. I’m saying that the comments make the bad code only slightly better. The aim of the game is to write good code.

BTW, I’m strong on mentoring; the idea that you let junior programmers (or other sorts of developers new to the code base) attack a code base without guidance is, to me, a bad idea symptomatic of a place with a lot of Level 2 code around.

I also supervise junior developers all the time. When I come across code I don’t understand quickly, I grab them, we do a code review, and we change the code to become Level 4 code in the review, as a collaborative process (dare I say “pair programming”? I do!). When they come across code I write that’s not clear to them, I tell them to grab me (or one of the other senior developers) and do the same thing. In the process, both the junior developer and myself will learn.

I’m also not saying that you don’t have other sources of information. (High-level) Design documents are still good, Javadoc is essential, a Wiki with advanced “tips and tricks” and coding idioms also work. My comment was strictly about comments.

Finally, as I stated in the original post, rather than have the junior developer be misled by an inaccurate comment, it’s better that they actually find out the truth. Heaven forbid that a junior programmer actually ask something what’s going on. If someone needs to “puzzle out” the meaning from the code, something’s wrong either with the code or their experience level. Determine which and fix it.

Which leads me to my next point: I can tell the maturity (a term I prefer over “seniority”) of a programmer by the comments they write. Not just by the fact that they write comments, but also by the way they phrase them and where they put them.

I totally agree; that’s my point. 🙂

Author: Robert Watkins

My name is Robert Watkins. I am a software developer and have been for over 20 years now. I currently work for people, but my opinions here are in no way endorsed by them (which is cool; their opinions aren’t endorsed by me either). My main professional interests are in Java development, using Agile methods, with a historical focus on building web based applications. I’m also a Mac-fan and love my iPhone, which I’m currently learning how to code for. I live and work in Brisbane, Australia, but I grew up in the Northern Territory, and still find Brisbane too cold (after 22 years here). I’m married, with two children and one cat. My politics are socialist in tendency, my religious affiliation is atheist (aka “none of the above”), my attitude is condescending and my moral standing is lying down. View all posts by Robert Watkins