Grammar.

I was working on a reply to Ayende's post on Working software over comprehensive documentation and I realized that I just don't care!

Okay, that's not true. Fact is, I've seen "literate" software arguments tossed around topsy-turvy in many forums over many years. It's a bit like TABs vs. SPACEs or Vi vs. EMACS. These arguments generally fail to acknowledge the simple fact that people work differently (and there's no accounting for poor taste and bad habits). Just kidding.

Instead of debating whether internal and external documentation deserve equal attention in the code, here are some of my observations on what constitutes effective documentation.

• It defines all of your nouns.
  What do objects represent?
• It defines all of your verbs.
  What do services do? How do objects behave?
• It defines all of your pronouns.
  How are objects externally identified?
• It defines all of your modifiers.
  How do configuration settings and option parameters affect services and objects?
• It defines all of your articles.
  What is the plurality of your components? Are they singletons?
• It defines all of your possessives.
  How are components aggregated?
• It defines all of your prepositions.
  What are the associations among components?
• It defines all of your phrases.
  How are useful modules constructed from the components provided?
• It defines all of your conjunctions.
  How are modules combined?
• It defines all of your sentences.
  How are complete self-contained applications assembled from the modules provided?
• It defines all of your grammatical rules and exceptions.
  What are the contracts to be satisfied by any given component? What are the constraints?
• It succinctly expresses clear, coherent and cohesive ideas.