--- title: A Taxonomy Of Comments | daily.dev description: A structured taxonomy of source code comments divided into four categories: Narrations (describing what code does), Contracts (declarative descriptions of... canonical: https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: A Taxonomy Of Comments | daily.dev og:description: A structured taxonomy of source code comments divided into four categories: Narrations (describing what code does), Contracts (declarative descriptions of... og:url: https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t og:image: https://api.daily.dev/og/posts/e8n3HsM3t.png og:image:alt: A Taxonomy Of Comments og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # A Taxonomy Of Comments **[nipafx \(Nicolai Parlog\)](https://daily.dev/sources/nipafx)** · 8 min read · 0 upvotes · 0 comments ## Summary A structured taxonomy of source code comments divided into four categories: Narrations (describing what code does), Contracts (declarative descriptions of behavior and pre/postconditions), Technical Context (explaining what code is for and how to use it), and Historical Context (explaining why code exists). Each category is analyzed across four dimensions: content goal, maintenance cost, preferred location, and viable alternatives. Narrations are generally discouraged in favor of clean code, contracts compete with tests, technical context supports learning, and historical context is best left to age gracefully or be replaced by commit messages and issue trackers. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Similar posts on daily.dev - [Maybe Comments SHOULD Explain 'What'](https://daily.dev/posts/maybe-comments-should-explain-what--za90dlcug) · Hacker News · 0 upvotes · 0 comments --- Tags: [#java](https://daily.dev/tags/java) [View this post on daily.dev](https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"A Taxonomy Of Comments","url":"https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t"},"datePublished":"2026-03-16T08:14:34.134Z","dateModified":"2026-03-16T08:29:15.620Z","description":"A structured taxonomy of source code comments divided into four categories: Narrations (describing what code does), Contracts (declarative descriptions of...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/f9c20a5070e656bd92381242ceded78b?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/f9c20a5070e656bd92381242ceded78b?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"nipafx (Nicolai Parlog)","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"nipafx (Nicolai Parlog)","logo":"https://media.daily.dev/image/upload/s--H_Echo_u--/f_auto,q_auto/v1773648772/logos/nipafx?_a=BAMAMiiu0","url":"https://daily.dev/sources/nipafx"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/a-taxonomy-of-comments-e8n3hsm3t","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"java","timeRequired":"PT8M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"nipafx (Nicolai Parlog)","item":"https://daily.dev/sources/nipafx"},{"@type":"ListItem","position":3,"name":"A Taxonomy Of Comments"}]} ```