John Yeary’s Documentation Advice triggers a Documentation Flashback


John Yeary wrote some useful suggestions for code documentation review: over on his blog. He has reasonable expectations for a Java developer, I think more people should write code level documentation, but unless you are shipping a public API of some sort, the reality of the industry is that no one writes documentation – ever.

Which is bad, you should write documentation. At least you should make an attempt at writing documentation before your project manager glares at you and tells you to get back to implementing requirements.

Anyway, it reminded me of a former employer that had a very curious approach to documentation. We weren’t allowed to write any. On top of not being allowed to write documentation, all method and variable names had to be descriptive. The first time the development lead had to talk to me about this, I seriously thought he was joking:

Him: “Ok, Tim. Um, that work you did yesterday, it’s great stuff, but you did something I’d like you to stop doing.”

Tim: “What you don’t want me to use JdbcTemplate?”

Him: “No, that’s not it… it’s the documentation. Our process doesn’t allow documentation, you need to make the code more descriptive.”

Tim: “That algorithm is complex, it’s recursive and a bit tricky. I just put a note in there to make sure that…”

Him: “Use a different algorithm, we can’t depend on it. All code has to be self-documenting.”

Tim: “Ok, sure, I’ll make the code self documentating boss.”

At University, I had a double major in Electrical Engineering and Sarcasm. A week passes, and all of my code turns into this:

public Patient loadsMedicalRecordAndUsesHibernateInsteadOfSQL( int patientId ) {
  HibernateSession session = loadHibernateSessionFromThreadLocal();
  Patient patient = session.load( Patient.class, patientId );
  return patient;
}

public static int calculateVisitsUsingAlgorithmToAccountForMultipleRecordSystems( Patient p, Hospital h, int visits ) {
  int numberOfVisitsCumulative = visits;
  numberOfVisitsCumulative +=  findNumberOfVisitsInHospitalRecordSystem( p );
  if( h.hasRelatedInsitutions() ) {
    int counterForRelatedInstitutions = 0;
    for( counterForRelatedInstitutions = 0; 
         counterForRelatedInsitutions < h.getRelatedInstitutions().size(); 
         counterForRelatedInsitutions++ ) {
     
      Hospital relatedInstitution = h.getRelatedInsitutions().get( counterForRelatedInstitutions );
      numberOfVisitsCumulative =  
        calculateVisitsUsingAlgorithmToAccountForMultipleRecordSystems( p, 
              relatedInstitution, numberOfVisitsCumulative );
    }
  }

  return numberOfVisitsCumulative; 

  }
}

Just imagine pages and pages of methods with names like “retrievingExactImmunizationScheduleWhileAccountingForNationalHolidaysInPatientLocale” or “calculatingBloodPressureUsingMeasurementsFromLastVisitToRelatedInstitution”.

What surprised me is that my boss liked what he saw. I turned my code into self-documenting code by taking the documentation and putting into all the class, method, and variable names. It was paralyzing for the team, really. My sarcastic attempt to prove a point turned into policy, or sorry “callMySarcasticAttemptAtTryingToProveAPointTurnedIntoPolicy”.