Am I missing the point?

Last Update: 11.04.2018. By Jens in Developers Life | Learning | Newsletter

Yesterday I talked about a case of Javadoc gone wrong. Reader Alejandro wrote in and thinks I am missing the main problem here because it is the code and not the Javadoc. I’d like to discuss that a bit further.

I am summarizing his points:

1. Javadoc or comments should not be necessary at all, because the code should be self-explaining
2. Comments tend to stay even after refactorings and do more harm aka confusion than helping
3. If the reader can’t understand the code one has written, it is bad code
4. If you document/comment then explain the why and not what His final advice was Write cleaner code and only write comment when necessary and only to explain why not what.

I agree, and I disagree with that.

Yes, you should name variables, methods, classes, etc. meaningful. It definitely helps to understand the code. But it is not always necessary, e.g., I think local variables are exceptions. It’s okay to name it hsId and not hotspotId in a single local context, mainly a method body. If it leaves the context, it is terrible.

Clear code helps in understanding and make many comments unnecessary, but not all. Comments are useful, and when we write them, they should be meaningful as I said last time. Stating the obvious is meaningless. Stating the reason why the code works like that or what the class or field is used for in a technical and/or business context. Many are self-explaining due good naming practice, but not all. Let’s say my example from yesterday looks like

public class Hotspot {

private String hotspotId; private String hotbenchId; // getter and setter * }*

I don’t know what hbId actually stood for, so let’s assume hotbenchId makes any sense in the context.

Clear code, understandable, right?

Yes, but it still does not help me.

It is missing aspects. It might be clear if you are already familiar with the context it is in if you know the project, the application, and the business cases. Maybe, but do you remember that coming back at that code and app after a 6-month pause? Do you still know what a hotspot is or the meaning of those two fields? Do you grasp it on sight?

Now imagine, you are the new guy on the project and, you got lucky, got a handover time of 4 weeks with the old guy. Maybe you’ll learn what a hotspot is from a business point, maybe not. Maybe the old guy passes down some tales of the system at hand. Maybe there is an outdated wiki/word/whatever. Poof, he is gone, and the next urgent tasks are waiting for you…

Have fun!

I’ve been in those shoes before. I’ve been the new guy on such systems, and I’ve been the idiot relying too much on clear code. Reading perfectly clear code, but still not grasping why the ancestors did solve X in way Y and what the business reason Z is. Sometimes, the folklore helped, sometimes it already got lost in ancient times.

A former colleague had a great name for that: Arcane Knowledge.