Hacker News new | past | comments | ask | show | jobs | submit login

I disagree. No one's asking for a literary masterpiece, just a simple and organized explanation of what we're looking at. I would argue that the value is more in the process of creating this simple explanation, because it forces you to empathetically examine the code from a a foreign mindset, and from there to re-order and organize the code in a way that's amenable to conversational (simple) explanation.

This explanation may include requirements and other concerns, description of alternatives and why they were rejected, references to other parts of the codebase, and its high-level design intention (i.e. vision) in order to guide the direction of refactorings and extensions.

None of this requires analogy, symbolism, foreshadowing, subtlety of tone, or even a mastery of diction and syntax. Anything resembling Yeats or Dostoyevsky is counter-productive.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact