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. 🙂