[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"sanity-FWzVa5b-aRVxgUNMmCtiZgrh9kai-lXm8X9KOOn-1rk":3,"sanity-E5wDa0XJ6o6DmTlRyKTLL0Yb-xSuiN0ok9x549JIvS4":1118},{"data":4,"sourceMap":-1},{"latestPodcast":5,"latestReleases":14,"post":39,"recent":1093},[6],{"_id":7,"publishedAt":8,"slug":9,"sponsored":12,"title":13},"50f4509c-4f55-4f11-8adc-5556e821ea77","2026-06-30T07:40:00.000Z",{"_type":10,"current":11},"slug","why-intent-prediction-needs-more-than-an-llm",null,"Why intent prediction needs more than an LLM",[15,21,27,33],{"_id":16,"publishedAt":17,"slug":18,"title":20},"eb5b66eb-9410-4329-83bb-22bbff39402a","2026-04-28T13:00:00.000Z",{"_type":10,"current":19},"turn-scattered-knowledge-into-trusted-intelligence","Turning scattered knowledge into trusted intelligence: Stack Internal 2026.3",{"_id":22,"publishedAt":23,"slug":24,"title":26},"369c2401-b62e-4a37-8ff8-bf603023ecad","2026-03-02T15:03:00.988Z",{"_type":10,"current":25},"what-s-new-at-stack-overflow-march-2026","What’s new at Stack Overflow: March 2026",{"_id":28,"publishedAt":29,"slug":30,"title":32},"5e9053a4-07ea-447c-91ea-29e0b6228537","2026-02-02T15:00:00.000Z",{"_type":10,"current":31},"what-s-new-at-stack-overflow-february-2026","What’s new at Stack Overflow: February 2026",{"_id":34,"publishedAt":35,"slug":36,"title":38},"a1b538eb-a8a6-46d0-80a1-ac70ec9bb935","2026-01-05T10:00:00.000-05:00",{"_type":10,"current":37},"what-s-new-at-stack-overflow-january-2026","What’s new at Stack Overflow: January 2026",{"_createdAt":40,"_id":41,"_rev":42,"_type":43,"_updatedAt":44,"author":45,"body":61,"comments":1067,"dateUrl":1068,"excerpt":1069,"image":1070,"legacyBody":1073,"product":12,"publishedAt":1076,"slug":1077,"sponsored":12,"tags":1079,"title":1092,"visible":1067},"2023-05-24T12:50:57Z","wp-post-18386","07ZbrKPSUrjrV4wQ6fJ274","blogPost","2023-07-13T14:56:11Z",[46],{"_createdAt":47,"_id":48,"_rev":49,"_type":50,"_updatedAt":51,"avatar":52,"employee":57,"name":58,"slug":59},"2023-05-23T16:27:18Z","wp-author-242","dgl3SCUzppW3U2LvCoP35A","blogAuthor","2023-06-20T15:05:08Z",{"_type":53,"asset":54},"image",{"_ref":55,"_type":56},"image-95df5348b1218788366ea950191019be16c98a8a-1024x1024-jpg","reference","none","Ellen Spertus",{"current":60},"espertus",[62,74,82,118,128,136,144,152,161,169,177,185,193,201,209,217,225,233,242,250,254,270,278,287,295,303,311,314,322,340,343,351,359,362,370,373,392,400,419,437,446,454,462,477,485,493,501,520,523,531,539,542,550,553,572,575,591,599,607,615,623,631,639,647,655,663,666,674,682,690,698,706,709,717,736,755,763,766,774,782,785,793,801,809,812,820,828,831,847,855,863,866,874,882,901,909,917,925,933,938,952,956,969,973,977,990,994,1004,1008,1025,1029,1039,1043,1053,1057],{"_key":63,"_type":64,"children":65,"markDefs":72,"style":73},"c2d5cff47fec","block",[66],{"_key":67,"_type":68,"marks":69,"text":71},"c2d5cff47fec0","span",[70],"em","[Ed. note: While we take some time to rest up over the holidays and prepare for next year, we are re-publishing our top ten posts for the year. Please enjoy our favorite work this year and we’ll see you in 2022.]",[],"normal",{"_key":75,"_type":64,"children":76,"markDefs":81,"style":73},"ad0a46d56986",[77],{"_key":78,"_type":68,"marks":79,"text":80},"ad0a46d569860",[],"Famed MIT professor Hal Abelson said: \"Programs must be written for people to read and only incidentally for machines to execute.\" While he may have purposely understated the importance of running code, he is spot on that programs have two very different audiences. Compilers and interpreters ignore comments and find all syntactically correct programs equally easy to understand. Human readers are very different. We find some programs harder to understand than others, and we look to comments to help us make sense of them.",[],{"_key":83,"_type":64,"children":84,"markDefs":114,"style":73},"4ff4fd8a0d72",[85,89,93,97,101,105,110],{"_key":86,"_type":68,"marks":87,"text":88},"4ff4fd8a0d720",[],"While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it's easy to measure the ",{"_key":90,"_type":68,"marks":91,"text":92},"4ff4fd8a0d721",[70],"quantity",{"_key":94,"_type":68,"marks":95,"text":96},"4ff4fd8a0d722",[]," of comments in a program, it's hard to measure the ",{"_key":98,"_type":68,"marks":99,"text":100},"4ff4fd8a0d723",[70],"quality",{"_key":102,"_type":68,"marks":103,"text":104},"4ff4fd8a0d724",[],", and the two are not necessarily correlated. A bad comment is worse than no comment at all. ",{"_key":106,"_type":68,"marks":107,"text":109},"4ff4fd8a0d725",[108],"4902761e7665","As Peter Vogel has written",{"_key":111,"_type":68,"marks":112,"text":113},"4ff4fd8a0d726",[],":",[115],{"_key":108,"_type":116,"href":117,"reference":12},"link","https://visualstudiomagazine.com/articles/2013/07/26/why-commenting-code-is-still-bad.aspx",{"_key":119,"_type":64,"children":120,"level":125,"listItem":126,"markDefs":127,"style":73},"4ea34e318fec",[121],{"_key":122,"_type":68,"marks":123,"text":124},"4ea34e318fec0",[],"Writing and then maintaining comments is an expense.",1,"number",[],{"_key":129,"_type":64,"children":130,"level":125,"listItem":126,"markDefs":135,"style":73},"c36f26606cfd",[131],{"_key":132,"_type":68,"marks":133,"text":134},"c36f26606cfd0",[],"Your compiler doesn't check your comments so there is no way to determine that comments are correct.",[],{"_key":137,"_type":64,"children":138,"level":125,"listItem":126,"markDefs":143,"style":73},"f17c87f61a91",[139],{"_key":140,"_type":68,"marks":141,"text":142},"f17c87f61a910",[],"You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to.",[],{"_key":145,"_type":64,"children":146,"markDefs":151,"style":73},"7b46afa074d8",[147],{"_key":148,"_type":68,"marks":149,"text":150},"7b46afa074d80",[],"While all of these points are true, it would be a mistake to go to the other extreme and never write comments. Here are some rules to help you achieve a happy medium:",[],{"_key":153,"_type":64,"children":154,"markDefs":160,"style":73},"c69852407586",[155],{"_key":156,"_type":68,"marks":157,"text":159},"c698524075860",[158],"strong","Rule 1: Comments should not duplicate the code.",[],{"_key":162,"_type":64,"children":163,"markDefs":168,"style":73},"9e696a7dba66",[164],{"_key":165,"_type":68,"marks":166,"text":167},"9e696a7dba660",[158],"Rule 2: Good comments do not excuse unclear code.",[],{"_key":170,"_type":64,"children":171,"markDefs":176,"style":73},"62e0cea7977e",[172],{"_key":173,"_type":68,"marks":174,"text":175},"62e0cea7977e0",[158],"Rule 3: If you can't write a clear comment, there may be a problem with the code.",[],{"_key":178,"_type":64,"children":179,"markDefs":184,"style":73},"d044c2d3419a",[180],{"_key":181,"_type":68,"marks":182,"text":183},"d044c2d3419a0",[158],"Rule 4: Comments should dispel confusion, not cause it.",[],{"_key":186,"_type":64,"children":187,"markDefs":192,"style":73},"9c8f0ee1d5ad",[188],{"_key":189,"_type":68,"marks":190,"text":191},"9c8f0ee1d5ad0",[158],"Rule 5: Explain unidiomatic code in comments.",[],{"_key":194,"_type":64,"children":195,"markDefs":200,"style":73},"b53c2f547ffb",[196],{"_key":197,"_type":68,"marks":198,"text":199},"b53c2f547ffb0",[158],"Rule 6: Provide links to the original source of copied code.",[],{"_key":202,"_type":64,"children":203,"markDefs":208,"style":73},"5deafe447219",[204],{"_key":205,"_type":68,"marks":206,"text":207},"5deafe4472190",[158],"Rule 7: Include links to external references where they will be most helpful.",[],{"_key":210,"_type":64,"children":211,"markDefs":216,"style":73},"7599a060f8db",[212],{"_key":213,"_type":68,"marks":214,"text":215},"7599a060f8db0",[158],"Rule 8: Add comments when fixing bugs.",[],{"_key":218,"_type":64,"children":219,"markDefs":224,"style":73},"8ada013b1e72",[220],{"_key":221,"_type":68,"marks":222,"text":223},"8ada013b1e720",[158],"Rule 9: Use comments to mark incomplete implementations.",[],{"_key":226,"_type":64,"children":227,"markDefs":232,"style":73},"7e91aa15d666",[228],{"_key":229,"_type":68,"marks":230,"text":231},"7e91aa15d6660",[],"The rest of this article explains each of these rules, providing examples and explaining how and when to apply them.",[],{"_key":234,"_type":64,"children":235,"markDefs":240,"style":241},"b7593c698a94",[236],{"_key":237,"_type":68,"marks":238,"text":239},"b7593c698a940",[],"Rule 1: Comments should not duplicate the code",[],"h2",{"_key":243,"_type":64,"children":244,"markDefs":249,"style":73},"86fc0fc769fd",[245],{"_key":246,"_type":68,"marks":247,"text":248},"86fc0fc769fd0",[],"Many junior programmers write too many comments because they were trained to do so by their introductory instructors. I've seen students in upper-division computer science classes add a comment to each closed brace to indicate what block is ending:",[],{"_key":251,"_type":252,"code":253,"markDefs":12},"a3f7b42f17a3","code","if (x > 3) {\n   …\n} // if",{"_key":255,"_type":64,"children":256,"markDefs":269,"style":73},"c2223f489ef7",[257,261,265],{"_key":258,"_type":68,"marks":259,"text":260},"c2223f489ef70",[],"I've also heard of instructors requiring students to comment every line of code. While this ",{"_key":262,"_type":68,"marks":263,"text":264},"c2223f489ef71",[70],"may",{"_key":266,"_type":68,"marks":267,"text":268},"c2223f489ef72",[]," be a reasonable policy for extreme beginners, such comments are like training wheels and should be removed when bicycling with the big kids.",[],{"_key":271,"_type":64,"children":272,"markDefs":277,"style":73},"178b42e21a2e",[273],{"_key":274,"_type":68,"marks":275,"text":276},"178b42e21a2e0",[],"Comments that add no information have negative value because they:",[],{"_key":279,"_type":64,"children":280,"level":125,"listItem":285,"markDefs":286,"style":73},"648a77711cfd",[281],{"_key":282,"_type":68,"marks":283,"text":284},"648a77711cfd0",[],"add visual clutter","bullet",[],{"_key":288,"_type":64,"children":289,"level":125,"listItem":285,"markDefs":294,"style":73},"afb9b4ad7af2",[290],{"_key":291,"_type":68,"marks":292,"text":293},"afb9b4ad7af20",[],"take time to write and read",[],{"_key":296,"_type":64,"children":297,"level":125,"listItem":285,"markDefs":302,"style":73},"3f5b2cb248ae",[298],{"_key":299,"_type":68,"marks":300,"text":301},"3f5b2cb248ae0",[],"can become out-of-date",[],{"_key":304,"_type":64,"children":305,"markDefs":310,"style":73},"ab902e5e52ce",[306],{"_key":307,"_type":68,"marks":308,"text":309},"ab902e5e52ce0",[],"The canonical bad example is:",[],{"_key":312,"_type":252,"code":313,"markDefs":12},"044947be1bfa","i = i + 1;         // Add one to i",{"_key":315,"_type":64,"children":316,"markDefs":321,"style":73},"29fea2232bc7",[317],{"_key":318,"_type":68,"marks":319,"text":320},"29fea2232bc70",[],"It adds no information whatsoever and incurs a maintenance cost.",[],{"_key":323,"_type":64,"children":324,"markDefs":337,"style":73},"49459adfe27b",[325,329,334],{"_key":326,"_type":68,"marks":327,"text":328},"49459adfe27b0",[],"Policies requiring comments for every line of code have been rightly ",{"_key":330,"_type":68,"marks":331,"text":333},"49459adfe27b1",[332],"e63a35919b8b","ridiculed on Reddit",{"_key":335,"_type":68,"marks":336,"text":113},"49459adfe27b2",[],[338],{"_key":332,"_type":116,"href":339,"reference":12},"https://www.reddit.com/r/ProgrammerHumor/comments/5dhdt6/my_teacher_told_me_i_needed_to_comment_every_line/da56d6m?utm_source=share&utm_medium=web2x&context=3",{"_key":341,"_type":252,"code":342,"markDefs":12},"de5876fe055d","// create a for loop // \u003C-- comment\nfor // start for loop\n(   // round bracket\n    // newline\nint // type for declaration\ni    // name for declaration\n=   // assignment operator for declaration\n0   // start value for i\n",{"_key":344,"_type":64,"children":345,"markDefs":350,"style":241},"7a09cfe08a5f",[346],{"_key":347,"_type":68,"marks":348,"text":349},"7a09cfe08a5f0",[],"Rule 2: Good comments do not excuse unclear code",[],{"_key":352,"_type":64,"children":353,"markDefs":358,"style":73},"5ac1f7be2164",[354],{"_key":355,"_type":68,"marks":356,"text":357},"5ac1f7be21640",[],"Another misuse of comments is to provide information that should have been in the code. A simple example is when someone names a variable with a single letter and then adds a comment describing its purpose:",[],{"_key":360,"_type":252,"code":361,"markDefs":12},"8859afbc61e0","private static Node getBestChildNode(Node node) {\n    Node n; // best child node candidate\n    for (Node node: node.getChildren()) {\n        // update n if the current state is better\n        if (n == null || utility(node) > utility(n)) {\n            n = node;\n        }\n    }\n    return n;\n} ",{"_key":363,"_type":64,"children":364,"markDefs":369,"style":73},"269a4534aa1d",[365],{"_key":366,"_type":68,"marks":367,"text":368},"269a4534aa1d0",[],"The need for comments could be eliminated with better variable naming:",[],{"_key":371,"_type":252,"code":372,"markDefs":12},"5b533864a98d","private static Node getBestChildNode(Node node) {\n    Node bestNode;\n    for (Node currentNode: node.getChildren()) {\n        if (bestNode == null || utility(currentNode) > utility(bestNode)) {\n            bestNode = currentNode;\n        }\n    }\n    return bestNode;\n} ",{"_key":374,"_type":64,"children":375,"markDefs":389,"style":73},"7a4ed24d63bc",[376,380,385],{"_key":377,"_type":68,"marks":378,"text":379},"7a4ed24d63bc0",[],"As Kernighan and Plauger wrote in ",{"_key":381,"_type":68,"marks":382,"text":384},"7a4ed24d63bc1",[383,70],"431f08720cc4","The Elements of Programming Style",{"_key":386,"_type":68,"marks":387,"text":388},"7a4ed24d63bc2",[],", \"Don't comment bad code — rewrite it.\"",[390],{"_key":383,"_type":116,"href":391,"reference":12},"https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style",{"_key":393,"_type":64,"children":394,"markDefs":399,"style":241},"cfaa49b7eef8",[395],{"_key":396,"_type":68,"marks":397,"text":398},"cfaa49b7eef80",[],"Rule 3: If you can't write a clear comment, there may be a problem with the code",[],{"_key":401,"_type":64,"children":402,"markDefs":416,"style":73},"27684ee1fb6f",[403,407,412],{"_key":404,"_type":68,"marks":405,"text":406},"27684ee1fb6f0",[],"The most infamous comment in the Unix source code is \"",{"_key":408,"_type":68,"marks":409,"text":411},"27684ee1fb6f1",[410],"f6dbf8547041","You are not expected to understand this",{"_key":413,"_type":68,"marks":414,"text":415},"27684ee1fb6f2",[],",\" which appeared before some hairy context-switching code. Dennis Ritchie later explained that it was intended \"in the spirit of 'This won't be on the exam,' rather than as an impudent challenge.\" Unfortunately, it turned out that he and co-author Ken Thompson didn't understand it themselves and later had to rewrite it.",[417],{"_key":410,"_type":116,"href":418,"reference":12},"https://web.archive.org/web/20070220094221/http://cm.bell-labs.com/cm/cs/who/dmr/odd.html",{"_key":420,"_type":64,"children":421,"markDefs":434,"style":73},"7c7305d525bc",[422,426,431],{"_key":423,"_type":68,"marks":424,"text":425},"7c7305d525bc0",[],"This brings to mind ",{"_key":427,"_type":68,"marks":428,"text":430},"7c7305d525bc1",[429],"cb66f9fed2df","Kernighan's Law",{"_key":432,"_type":68,"marks":433,"text":113},"7c7305d525bc2",[],[435],{"_key":429,"_type":116,"href":436,"reference":12},"https://github.com/dwmkerr/hacker-laws#kernighans-law",{"_key":438,"_type":64,"children":439,"markDefs":444,"style":445},"83e357004337",[440],{"_key":441,"_type":68,"marks":442,"text":443},"83e3570043370",[],"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.",[],"blockquote",{"_key":447,"_type":64,"children":448,"markDefs":453,"style":73},"c28bdb8a543e",[449],{"_key":450,"_type":68,"marks":451,"text":452},"c28bdb8a543e0",[],"Warning readers away from your code is like turning on your car's hazard lights: an admission that you're doing something you know is illegal. Instead, rewrite the code to something you understand well enough to explain or, better yet, that is straightforward.",[],{"_key":455,"_type":64,"children":456,"markDefs":461,"style":241},"4814abad0997",[457],{"_key":458,"_type":68,"marks":459,"text":460},"4814abad09970",[],"Rule 4: Comments should dispel confusion, not cause it",[],{"_key":463,"_type":64,"children":464,"markDefs":476,"style":73},"224c1c9f3176",[465,469,473],{"_key":466,"_type":68,"marks":467,"text":468},"224c1c9f31760",[],"No discussion of bad comments would be complete without this story from Steven Levy's ",{"_key":470,"_type":68,"marks":471,"text":472},"224c1c9f31761",[70],"Hackers: Heroes of the Computer Revolution",{"_key":474,"_type":68,"marks":475,"text":113},"224c1c9f31762",[],[],{"_key":478,"_type":64,"children":479,"markDefs":484,"style":445},"a757f30f822d",[480],{"_key":481,"_type":68,"marks":482,"text":483},"a757f30f822d0",[],"[Peter Samson] was particularly obscure in refusing to add comments to his source code explaining what he was doing at a given time. One well-distributed program Samson wrote went on for hundreds of assembly-language instructions, with only one comment beside an instruction that contained the number 1750. The comment was RIPJSB, and people racked their brains about its meaning until someone figured out that 1750 was the year Bach died, and that Samson had written an abbreviation for Rest In Peace Johann Sebastian Bach.",[],{"_key":486,"_type":64,"children":487,"markDefs":492,"style":73},"d36a38f6c310",[488],{"_key":489,"_type":68,"marks":490,"text":491},"d36a38f6c3100",[],"While I appreciate a good hack as much as the next person, this is not exemplary. If your comment causes confusion instead of dispelling it, remove it.",[],{"_key":494,"_type":64,"children":495,"markDefs":500,"style":241},"1a1c3f9bb0b1",[496],{"_key":497,"_type":68,"marks":498,"text":499},"1a1c3f9bb0b10",[],"Rule 5: Explain unidiomatic code in comments",[],{"_key":502,"_type":64,"children":503,"markDefs":517,"style":73},"1fe628c9daec",[504,508,513],{"_key":505,"_type":68,"marks":506,"text":507},"1fe628c9daec0",[],"It's a good idea to comment code that someone else might consider unneeded or redundant, such as this code from ",{"_key":509,"_type":68,"marks":510,"text":512},"1fe628c9daec1",[511],"2ce88528d73d","App Inventor",{"_key":514,"_type":68,"marks":515,"text":516},"1fe628c9daec2",[]," (the source of all of my positive examples):",[518],{"_key":511,"_type":116,"href":519,"reference":12},"https://github.com/mit-cml/appinventor-sources",{"_key":521,"_type":252,"code":522,"markDefs":12},"1da3deafe3d2","final Object value = (new JSONTokener(jsonString)).nextValue();\n// Note that JSONTokener.nextValue() may return\n// a value equals() to null.\nif (value == null || value.equals(null)) {\n    return null;\n}\n",{"_key":524,"_type":64,"children":525,"markDefs":530,"style":73},"b903dca6a3f8",[526],{"_key":527,"_type":68,"marks":528,"text":529},"b903dca6a3f80",[],"Without the comment, someone might \"simplify\" the code or view it as a mysterious but essential incantation. Save future readers time and anxiety by writing down why the code is needed.",[],{"_key":532,"_type":64,"children":533,"markDefs":538,"style":73},"9029069d12df",[534],{"_key":535,"_type":68,"marks":536,"text":537},"9029069d12df0",[],"A judgment call needs to be made as to whether code requires explanation. When learning Kotlin, I encountered code in an Android tutorial of the form:",[],{"_key":540,"_type":252,"code":541,"markDefs":12},"ddddc1c3944a","if (b == true)",{"_key":543,"_type":64,"children":544,"markDefs":549,"style":73},"1ffbf15f7e08",[545],{"_key":546,"_type":68,"marks":547,"text":548},"1ffbf15f7e080",[],"I immediately wondered whether it could be replaced with:",[],{"_key":551,"_type":252,"code":552,"markDefs":12},"be847ac72863","if (b)",{"_key":554,"_type":64,"children":555,"markDefs":569,"style":73},"b1dce679f267",[556,560,565],{"_key":557,"_type":68,"marks":558,"text":559},"b1dce679f2670",[],"as one would do in Java. After a little ",{"_key":561,"_type":68,"marks":562,"text":564},"b1dce679f2671",[563],"0a71a44b7d10","research",{"_key":566,"_type":68,"marks":567,"text":568},"b1dce679f2672",[],", I learned that nullable Boolean variables are explicitly compared to true in order to avoid an ugly null check:",[570],{"_key":563,"_type":116,"href":571,"reference":12},"https://kotlinlang.org/docs/idioms.html#nullable-boolean",{"_key":573,"_type":252,"code":574,"markDefs":12},"ff06c2ce34f5","if (b != null && b)",{"_key":576,"_type":64,"children":577,"markDefs":590,"style":73},"fa9099073760",[578,582,586],{"_key":579,"_type":68,"marks":580,"text":581},"fa90990737600",[],"I recommend ",{"_key":583,"_type":68,"marks":584,"text":585},"fa90990737601",[70],"not ",{"_key":587,"_type":68,"marks":588,"text":589},"fa90990737602",[],"including comments for common idioms unless writing a tutorial specifically for novices.",[],{"_key":592,"_type":64,"children":593,"markDefs":598,"style":241},"22f1d76c87ad",[594],{"_key":595,"_type":68,"marks":596,"text":597},"22f1d76c87ad0",[],"Rule 6: Provide links to the original source of copied code",[],{"_key":600,"_type":64,"children":601,"markDefs":606,"style":73},"1e9f0620694b",[602],{"_key":603,"_type":68,"marks":604,"text":605},"1e9f0620694b0",[],"If you're like most programmers, you sometimes use code that you find online. Including a reference to the source enables future readers to get the full context, such as:",[],{"_key":608,"_type":64,"children":609,"level":125,"listItem":285,"markDefs":614,"style":73},"05b3a80dbab3",[610],{"_key":611,"_type":68,"marks":612,"text":613},"05b3a80dbab30",[],"what problem was being solved",[],{"_key":616,"_type":64,"children":617,"level":125,"listItem":285,"markDefs":622,"style":73},"c06a4873b2f6",[618],{"_key":619,"_type":68,"marks":620,"text":621},"c06a4873b2f60",[],"who provided the code",[],{"_key":624,"_type":64,"children":625,"level":125,"listItem":285,"markDefs":630,"style":73},"d7a352eb775c",[626],{"_key":627,"_type":68,"marks":628,"text":629},"d7a352eb775c0",[],"why the solution is recommended",[],{"_key":632,"_type":64,"children":633,"level":125,"listItem":285,"markDefs":638,"style":73},"e60f2ca0fc7d",[634],{"_key":635,"_type":68,"marks":636,"text":637},"e60f2ca0fc7d0",[],"what commenters thought of it",[],{"_key":640,"_type":64,"children":641,"level":125,"listItem":285,"markDefs":646,"style":73},"ec6be63e1b53",[642],{"_key":643,"_type":68,"marks":644,"text":645},"ec6be63e1b530",[],"whether it still works",[],{"_key":648,"_type":64,"children":649,"level":125,"listItem":285,"markDefs":654,"style":73},"e685cd8d8eda",[650],{"_key":651,"_type":68,"marks":652,"text":653},"e685cd8d8eda0",[],"how it can be improved",[],{"_key":656,"_type":64,"children":657,"markDefs":662,"style":73},"dae1ede5103b",[658],{"_key":659,"_type":68,"marks":660,"text":661},"dae1ede5103b0",[],"For example, consider this comment:",[],{"_key":664,"_type":252,"code":665,"markDefs":12},"382ab896d0c7","/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */",{"_key":667,"_type":64,"children":668,"markDefs":673,"style":73},"ef13eeb5b3df",[669],{"_key":670,"_type":68,"marks":671,"text":672},"ef13eeb5b3df0",[],"Following the link to the answer reveals:",[],{"_key":675,"_type":64,"children":676,"level":125,"listItem":285,"markDefs":681,"style":73},"f3fc2c4122e0",[677],{"_key":678,"_type":68,"marks":679,"text":680},"f3fc2c4122e00",[],"The author of the code is Tomáš Procházka, who is in the top 3% on Stack Overflow.",[],{"_key":683,"_type":64,"children":684,"level":125,"listItem":285,"markDefs":689,"style":73},"2de3bc78e0ed",[685],{"_key":686,"_type":68,"marks":687,"text":688},"2de3bc78e0ed0",[],"One commenter provides an optimization, already incorporated into the repo.",[],{"_key":691,"_type":64,"children":692,"level":125,"listItem":285,"markDefs":697,"style":73},"52caeb5083dd",[693],{"_key":694,"_type":68,"marks":695,"text":696},"52caeb5083dd0",[],"Another commenter suggests a way to avoid an edge case.",[],{"_key":699,"_type":64,"children":700,"markDefs":705,"style":73},"ca60fcfa16a2",[701],{"_key":702,"_type":68,"marks":703,"text":704},"ca60fcfa16a20",[],"Contrast it with this comment (slightly altered to protect the guilty):",[],{"_key":707,"_type":252,"code":708,"markDefs":12},"d00a0ec44708","// Magical formula taken from a stackoverflow post, reputedly related to\n// human vision perception.\nreturn (int) (0.3 * red + 0.59 * green + 0.11 * blue);",{"_key":710,"_type":64,"children":711,"markDefs":716,"style":73},"90b331cd4100",[712],{"_key":713,"_type":68,"marks":714,"text":715},"90b331cd41000",[],"Anyone looking to understand this code is going to have to search for the formula. Pasting in the URL is much quicker than later finding the reference.",[],{"_key":718,"_type":64,"children":719,"markDefs":733,"style":73},"1e45a2071edc",[720,724,729],{"_key":721,"_type":68,"marks":722,"text":723},"1e45a2071edc0",[],"Some programmers may be reluctant to indicate that they did not write code themselves, but reusing code can be a smart move, saving time and giving you the benefit of more eyeballs. Of course, you should ",{"_key":725,"_type":68,"marks":726,"text":728},"1e45a2071edc1",[727],"d0365ca2ac74","never paste in code that you don't understand",{"_key":730,"_type":68,"marks":731,"text":732},"1e45a2071edc2",[],".",[734],{"_key":727,"_type":116,"href":735,"reference":12},"https://stackoverflow.blog/2019/11/26/copying-code-from-stack-overflow-you-might-be-spreading-security-vulnerabilities/",{"_key":737,"_type":64,"children":738,"markDefs":752,"style":73},"d3ca7b3f2cf5",[739,743,748],{"_key":740,"_type":68,"marks":741,"text":742},"d3ca7b3f2cf50",[],"People ",{"_key":744,"_type":68,"marks":745,"text":747},"d3ca7b3f2cf51",[746],"e1d894440b18","copy a lot of code",{"_key":749,"_type":68,"marks":750,"text":751},"d3ca7b3f2cf52",[]," from Stack Overflow questions and answers. That code falls under Creative Commons licenses requiring attribution. A reference comment satisfies that requirement.",[753],{"_key":746,"_type":116,"href":754,"reference":12},"https://stackoverflow.blog/2021/04/19/how-often-do-people-actually-copy-and-paste-from-stack-overflow-now-we-know/",{"_key":756,"_type":64,"children":757,"markDefs":762,"style":73},"ca5796c27a6e",[758],{"_key":759,"_type":68,"marks":760,"text":761},"ca5796c27a6e0",[],"Similarly, you should reference tutorials that were helpful, so they can be found again and as thanks to their author:",[],{"_key":764,"_type":252,"code":765,"markDefs":12},"d464cc52f099","// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html\n// for a great reference and examples.",{"_key":767,"_type":64,"children":768,"markDefs":773,"style":241},"6b31f6fe1258",[769],{"_key":770,"_type":68,"marks":771,"text":772},"6b31f6fe12580",[],"Rule 7: Include links to external references where they will be most helpful",[],{"_key":775,"_type":64,"children":776,"markDefs":781,"style":73},"c09577e6b195",[777],{"_key":778,"_type":68,"marks":779,"text":780},"c09577e6b1950",[],"Of course, not all references are to Stack Overflow. Consider:",[],{"_key":783,"_type":252,"code":784,"markDefs":12},"2c68d38feebe","// http://tools.ietf.org/html/rfc4180 suggests that CSV lines\n// should be terminated by CRLF, hence the \\r\\n.\ncsvStringBuilder.append(\"\\r\\n\");\n",{"_key":786,"_type":64,"children":787,"markDefs":792,"style":73},"282fa033c7c5",[788],{"_key":789,"_type":68,"marks":790,"text":791},"282fa033c7c50",[],"Links to standards and other documentation can help readers understand the problem your code is solving. While this information may be somewhere in a design document, a well-placed comment gives readers the pointer when and where it is most needed. In this case, following the link indicates that RFC 4180 has been updated by RFC 7111—useful information.",[],{"_key":794,"_type":64,"children":795,"markDefs":800,"style":241},"cd3bbc672626",[796],{"_key":797,"_type":68,"marks":798,"text":799},"cd3bbc6726260",[],"Rule 8: Add comments when fixing bugs",[],{"_key":802,"_type":64,"children":803,"markDefs":808,"style":73},"a23fa76db11c",[804],{"_key":805,"_type":68,"marks":806,"text":807},"a23fa76db11c0",[],"Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs. Consider this comment:",[],{"_key":810,"_type":252,"code":811,"markDefs":12},"8fa3bf69bb99","  // NOTE: At least in Firefox 2, if the user drags outside of the browser window,\n  // mouse-move (and even mouse-down) events will not be received until\n  // the user drags back inside the window. A workaround for this issue\n  // exists in the implementation for onMouseLeave().\n  @Override\n  public void onMouseMove(Widget sender, int x, int y) { .. }\n",{"_key":813,"_type":64,"children":814,"markDefs":819,"style":73},"3819b7e8fb60",[815],{"_key":816,"_type":68,"marks":817,"text":818},"3819b7e8fb600",[],"Not only does the comment help the reader understand the code in the current and referenced methods, it is helpful for determining whether the code is still needed and how to test it.",[],{"_key":821,"_type":64,"children":822,"markDefs":827,"style":73},"8eeaa8df0b3a",[823],{"_key":824,"_type":68,"marks":825,"text":826},"8eeaa8df0b3a0",[],"It can also be helpful to reference issue trackers:",[],{"_key":829,"_type":252,"code":830,"markDefs":12},"b989be50a9c8","// Use the name as the title if the properties did not include one (issue #1425)",{"_key":832,"_type":64,"children":833,"markDefs":846,"style":73},"ace9634eb9e6",[834,838,842],{"_key":835,"_type":68,"marks":836,"text":837},"ace9634eb9e60",[],"While ",{"_key":839,"_type":68,"marks":840,"text":841},"ace9634eb9e61",[252],"git blame",{"_key":843,"_type":68,"marks":844,"text":845},"ace9634eb9e62",[]," can be used to find the commit in which a line was added or modified, commit messages tend to be brief, and the most important change (e.g., fixing issue #1425) may not be part of the most recent commit (e.g., moving a method from one file to another).",[],{"_key":848,"_type":64,"children":849,"markDefs":854,"style":241},"7ba1f2b38b92",[850],{"_key":851,"_type":68,"marks":852,"text":853},"7ba1f2b38b920",[],"Rule 9: Use comments to mark incomplete implementations",[],{"_key":856,"_type":64,"children":857,"markDefs":862,"style":73},"a1a1d4784172",[858],{"_key":859,"_type":68,"marks":860,"text":861},"a1a1d47841720",[],"Sometimes it's necessary to check in code even though it has known limitations. While it can be tempting not to share known deficiencies in one's code, it is better to make these explicit, such as with a TODO comment:",[],{"_key":864,"_type":252,"code":865,"markDefs":12},"0497964a9ab9","// TODO(hal): We are making the decimal separator be a period, \n// regardless of the locale of the phone. We need to think about \n// how to allow comma as decimal separator, which will require \n// updating number parsing and other places that transform numbers \n// to strings, such as FormatAsDecimal\n",{"_key":867,"_type":64,"children":868,"markDefs":873,"style":73},"2f4282f4d0fb",[869],{"_key":870,"_type":68,"marks":871,"text":872},"2f4282f4d0fb0",[],"Using a standard format for such comments helps with measuring and addressing technical debt. Better yet, add an issue to your tracker, and reference the issue in your comment.",[],{"_key":875,"_type":64,"children":876,"markDefs":881,"style":241},"47fe910ab5ec",[877],{"_key":878,"_type":68,"marks":879,"text":880},"47fe910ab5ec0",[],"Conclusion",[],{"_key":883,"_type":64,"children":884,"markDefs":898,"style":73},"de404958909e",[885,889,894],{"_key":886,"_type":68,"marks":887,"text":888},"de404958909e0",[],"I hope the above examples have shown that comments don't excuse or fix bad code; they complement good code by providing a different type of information. As Stack Overflow co-founder Jeff Atwood has written, \"",{"_key":890,"_type":68,"marks":891,"text":893},"de404958909e1",[892],"ac74f1094ba7","Code Tells You How, Comments Tell You Why",{"_key":895,"_type":68,"marks":896,"text":897},"de404958909e2",[],".\"",[899],{"_key":892,"_type":116,"href":900,"reference":12},"https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/",{"_key":902,"_type":64,"children":903,"markDefs":908,"style":73},"4f4835c3a077",[904],{"_key":905,"_type":68,"marks":906,"text":907},"4f4835c3a0770",[],"Following these rules should save you and your teammates time and frustration.",[],{"_key":910,"_type":64,"children":911,"markDefs":916,"style":73},"de0f8fd2a7c1",[912],{"_key":913,"_type":68,"marks":914,"text":915},"de0f8fd2a7c10",[],"That said, I'm sure these rules aren't exhaustive and look forward to seeing suggested additions in (where else?) the comments.",[],{"_key":918,"_type":64,"children":919,"markDefs":924,"style":241},"b6e4501e29f2",[920],{"_key":921,"_type":68,"marks":922,"text":923},"b6e4501e29f20",[],"Memes and cartoons",[],{"_key":926,"_type":64,"children":927,"markDefs":932,"style":73},"b8e920da5e8a",[928],{"_key":929,"_type":68,"marks":930,"text":931},"b8e920da5e8a0",[],"For your consideration...",[],{"_key":934,"_type":53,"alt":12,"asset":935,"caption":937,"markDefs":12},"e95a83de0b3a",{"_ref":936,"_type":56},"image-e487213c090116f194f2ed4fc6b0bfbece5258be-531x563-png","",{"_key":939,"_type":64,"children":940,"markDefs":950,"style":73},"f9c8331fa727",[941,945],{"_key":942,"_type":68,"marks":943,"text":944},"f9c8331fa7270",[],"Source: ",{"_key":946,"_type":68,"marks":947,"text":949},"f9c8331fa7271",[948],"77676175b63d","https://www.reddit.com/r/ProgrammerHumor/comments/8w54mx/code_comments_be_like/",[951],{"_key":948,"_type":116,"href":949,"reference":12},{"_key":953,"_type":53,"alt":12,"asset":954,"caption":937,"markDefs":12},"0f1edd903563",{"_ref":955,"_type":56},"image-4ad7a0bd338d7616a7900b9c94b7bd2c53da825e-794x590-png",{"_key":957,"_type":64,"children":958,"markDefs":967,"style":73},"337c9da247a5",[959,962],{"_key":960,"_type":68,"marks":961,"text":944},"337c9da247a50",[],{"_key":963,"_type":68,"marks":964,"text":966},"337c9da247a51",[965],"0e55a96f3926","https://www.reddit.com/r/ProgrammerHumor/comments/bz35nh/whats_a_comment/",[968],{"_key":965,"_type":116,"href":966,"reference":12},{"_key":970,"_type":53,"alt":12,"asset":971,"caption":937,"markDefs":12},"e09f80294537",{"_ref":972,"_type":56},"image-eb80ecc70d0296a33ccbd48c545efa2580a11d1d-800x1133-png",{"_key":974,"_type":53,"alt":12,"asset":975,"caption":937,"markDefs":12},"603ac243fefa",{"_ref":976,"_type":56},"image-86b21756b72b6fe487b62efcf49c0378350bc3f9-700x218-png",{"_key":978,"_type":64,"children":979,"markDefs":988,"style":73},"db5ca6e08cff",[980,983],{"_key":981,"_type":68,"marks":982,"text":944},"db5ca6e08cff0",[],{"_key":984,"_type":68,"marks":985,"text":987},"db5ca6e08cff1",[986],"ad40795c65ab","https://geekandpoke.typepad.com/geekandpoke/2011/06/code-commenting-made-easy.html",[989],{"_key":986,"_type":116,"href":987,"reference":12},{"_key":991,"_type":53,"alt":12,"asset":992,"caption":937,"markDefs":12},"9e90514a9b4c",{"_ref":993,"_type":56},"image-e3cd489514d085e88b9ccd94ab5f3218adc7283b-480x680-png",{"_key":995,"_type":64,"children":996,"markDefs":1002,"style":73},"355cafebaab8",[997],{"_key":998,"_type":68,"marks":999,"text":1001},"355cafebaab80",[1000],"e983f2932853","https://geekandpoke.typepad.com/geekandpoke/2008/07/good-comments.html",[1003],{"_key":1000,"_type":116,"href":1001,"reference":12},{"_key":1005,"_type":53,"alt":12,"asset":1006,"caption":937,"markDefs":12},"b7fcc1790c88",{"_ref":1007,"_type":56},"image-2640d282b6b7988d0ee8634119371b80cba222f0-650x604-png",{"_key":1009,"_type":64,"children":1010,"markDefs":1023,"style":73},"fd90febf6a9c",[1011,1014,1019],{"_key":1012,"_type":68,"marks":1013,"text":944},"fd90febf6a9c0",[],{"_key":1015,"_type":68,"marks":1016,"text":1018},"fd90febf6a9c1",[1017],"75fba3fbd000","https://www.commitstrip.com/en/2016/09/01/keep-it-simple-stupid/",{"_key":1020,"_type":68,"marks":1021,"text":1022},"fd90febf6a9c2",[],"?",[1024],{"_key":1017,"_type":116,"href":1018,"reference":12},{"_key":1026,"_type":53,"alt":12,"asset":1027,"caption":937,"markDefs":12},"08578c34c1d0",{"_ref":1028,"_type":56},"image-1f7e9af23b3fcfee355f53fd9b70c4774894bcd6-600x640-png",{"_key":1030,"_type":64,"children":1031,"markDefs":1037,"style":73},"68b09c3a06a6",[1032],{"_key":1033,"_type":68,"marks":1034,"text":1036},"68b09c3a06a60",[1035],"1085d7dfe3cb","https://www.commitstrip.com/en/2013/07/22/commentaire-de-commit/?",[1038],{"_key":1035,"_type":116,"href":1036,"reference":12},{"_key":1040,"_type":53,"alt":12,"asset":1041,"caption":937,"markDefs":12},"e623ecda0a6e",{"_ref":1042,"_type":56},"image-129eaa8b9658579dfd753c977ffeb22b25e04c79-800x1134-png",{"_key":1044,"_type":64,"children":1045,"markDefs":1051,"style":73},"8a3e9140c961",[1046],{"_key":1047,"_type":68,"marks":1048,"text":1050},"8a3e9140c9610",[1049],"4398fd6facd8","https://geekandpoke.typepad.com/geekandpoke/2009/07/",[1052],{"_key":1049,"_type":116,"href":1050,"reference":12},{"_key":1054,"_type":53,"alt":12,"asset":1055,"caption":937,"markDefs":12},"f20039c3ad43",{"_ref":1056,"_type":56},"image-3ccfea010d425e9a394161e21cf1ce82f05c5cdf-800x1133-png",{"_key":1058,"_type":64,"children":1059,"markDefs":1065,"style":73},"45c9c51f70a4",[1060],{"_key":1061,"_type":68,"marks":1062,"text":1064},"45c9c51f70a40",[1063],"87e30e6258dd","https://geekandpoke.typepad.com/geekandpoke/2010/11/architecture.html",[1066],{"_key":1063,"_type":116,"href":1064,"reference":12},true,"2021/12/23","While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it's easy to measure the quantity of comments in a program, it's hard to measure the quality, and the two are not necessarily correlated. A bad comment is worse than no comment at all. Here are some rules to help you achieve a happy medium.",{"_type":53,"asset":1071},{"_ref":1072,"_type":56},"image-414a8fbdab9119e924482a44f8c314a09e388768-1200x630-png",{"code":1074,"language":1075},"\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cem>[Ed. note: While we take some time to rest up over the holidays and prepare for next year, we are re-publishing our top ten posts for the year. Please enjoy our favorite work this year and we’ll see you in 2022.]\u003C/em>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Famed MIT professor Hal Abelson said: \"Programs must be written for people to read and only incidentally for machines to execute.\" While he may have purposely understated the importance of running code, he is spot on that programs have two very different audiences. Compilers and interpreters ignore comments and find all syntactically correct programs equally easy to understand. Human readers are very different. We find some programs harder to understand than others, and we look to comments to help us make sense of them. \u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>While there are many resources to help programmers write better code—such as books and static analyzers—there are few for writing better comments. While it's easy to measure the \u003Cem>quantity\u003C/em> of comments in a program, it's hard to measure the \u003Cem>quality\u003C/em>, and the two are not necessarily correlated. A bad comment is worse than no comment at all. \u003Ca href=\"https://visualstudiomagazine.com/articles/2013/07/26/why-commenting-code-is-still-bad.aspx\">As Peter Vogel has written\u003C/a>:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:list {\"ordered\":true} -->\n\u003Col>\u003Cli>Writing and then maintaining comments is an expense.\u003C/li>\u003Cli>Your compiler doesn't check your comments so there is no way to determine that comments are correct.\u003C/li>\u003Cli>You are, on the other hand, guaranteed that the computer is doing exactly what your code is telling it to.\u003C/li>\u003C/ol>\n\u003C!-- /wp:list -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>While all of these points are true, it would be a mistake to go to the other extreme and never write comments. Here are some rules to help you achieve a happy medium:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 1: Comments should not duplicate the code.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 2: Good comments do not excuse unclear code.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 3: If you can't write a clear comment, there may be a problem with the code.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 4: Comments should dispel confusion, not cause it.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 5: Explain unidiomatic code in comments.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 6: Provide links to the original source of copied code.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 7: Include links to external references where they will be most helpful.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 8: Add comments when fixing bugs.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Cstrong>Rule 9: Use comments to mark incomplete implementations.\u003C/strong>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>The rest of this article explains each of these rules, providing examples and explaining how and when to apply them.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-1-comments-should-not-duplicate-the-code\">Rule 1: Comments should not duplicate the code\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Many junior programmers write too many comments because they were trained to do so by their introductory instructors. I've seen students in upper-division computer science classes add a comment to each closed brace to indicate what block is ending:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>if (x > 3) {\n   …\n} // if\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>I've also heard of instructors requiring students to comment every line of code. While this \u003Cem>may\u003C/em> be a reasonable policy for extreme beginners, such comments are like training wheels and should be removed when bicycling with the big kids.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Comments that add no information have negative value because they:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:list -->\n\u003Cul>\u003Cli>add visual clutter\u003C/li>\u003Cli>take time to write and read\u003C/li>\u003Cli>can become out-of-date\u003C/li>\u003C/ul>\n\u003C!-- /wp:list -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>The canonical bad example is:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>i = i + 1;         // Add one to i\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>It adds no information whatsoever and incurs a maintenance cost.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Policies requiring comments for every line of code have been rightly \u003Ca href=\"https://www.reddit.com/r/ProgrammerHumor/comments/5dhdt6/my_teacher_told_me_i_needed_to_comment_every_line/da56d6m?utm_source=share&utm_medium=web2x&context=3\">ridiculed on Reddit\u003C/a>:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// create a for loop // <-- comment\nfor // start for loop\n(   // round bracket\n    // newline\nint // type for declaration\ni    // name for declaration\n=   // assignment operator for declaration\n0   // start value for i\n\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-2-good-comments-do-not-excuse-unclear-code\">Rule 2: Good comments do not excuse unclear code\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Another misuse of comments is to provide information that should have been in the code. A simple example is when someone names a variable with a single letter and then adds a comment describing its purpose:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>private static Node getBestChildNode(Node node) {\n    Node n; // best child node candidate\n    for (Node node: node.getChildren()) {\n        // update n if the current state is better\n        if (n == null || utility(node) > utility(n)) {\n            n = node;\n        }\n    }\n    return n;\n} \u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>The need for comments could be eliminated with better variable naming:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>private static Node getBestChildNode(Node node) {\n    Node bestNode;\n    for (Node currentNode: node.getChildren()) {\n        if (bestNode == null || utility(currentNode) > utility(bestNode)) {\n            bestNode = currentNode;\n        }\n    }\n    return bestNode;\n} \u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>As Kernighan and Plauger wrote in \u003Ca href=\"https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style\">\u003Cem>The Elements of Programming Style\u003C/em>\u003C/a>, \"Don't comment bad code — rewrite it.\"\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-3-if-you-can-t-write-a-clear-comment-there-may-be-a-problem-with-the-code\">Rule 3: If you can't write a clear comment, there may be a problem with the code\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>The most infamous comment in the Unix source code is \"\u003Ca href=\"https://web.archive.org/web/20070220094221/http://cm.bell-labs.com/cm/cs/who/dmr/odd.html\">You are not expected to understand this\u003C/a>,\" which appeared before some hairy context-switching code. Dennis Ritchie later explained that it was intended \"in the spirit of 'This won't be on the exam,' rather than as an impudent challenge.\" Unfortunately, it turned out that he and co-author Ken Thompson didn't understand it themselves and later had to rewrite it.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>This brings to mind \u003Ca href=\"https://github.com/dwmkerr/hacker-laws#kernighans-law\">Kernighan's Law\u003C/a>:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:quote -->\n\u003Cblockquote class=\"wp-block-quote\">\u003Cp>Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.\u003C/p>\u003C/blockquote>\n\u003C!-- /wp:quote -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Warning readers away from your code is like turning on your car's hazard lights: an admission that you're doing something you know is illegal. Instead, rewrite the code to something you understand well enough to explain or, better yet, that is straightforward.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-4-comments-should-dispel-confusion-not-cause-it\">Rule 4: Comments should dispel confusion, not cause it\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>No discussion of bad comments would be complete without this story from Steven Levy's \u003Cem>Hackers: Heroes of the Computer Revolution\u003C/em>:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:quote -->\n\u003Cblockquote class=\"wp-block-quote\">\u003Cp>[Peter Samson] was particularly obscure in refusing to add comments to his source code explaining what he was doing at a given time. One well-distributed program Samson wrote went on for hundreds of assembly-language instructions, with only one comment beside an instruction that contained the number 1750. The comment was RIPJSB, and people racked their brains about its meaning until someone figured out that 1750 was the year Bach died, and that Samson had written an abbreviation for Rest In Peace Johann Sebastian Bach.\u003C/p>\u003C/blockquote>\n\u003C!-- /wp:quote -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>While I appreciate a good hack as much as the next person, this is not exemplary. If your comment causes confusion instead of dispelling it, remove it.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-5-explain-unidiomatic-code-in-comments\">Rule 5: Explain unidiomatic code in comments\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>It's a good idea to comment code that someone else might consider unneeded or redundant, such as this code from \u003Ca href=\"https://github.com/mit-cml/appinventor-sources\">App Inventor\u003C/a> (the source of all of my positive examples):\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>final Object value = (new JSONTokener(jsonString)).nextValue();\n// Note that JSONTokener.nextValue() may return\n// a value equals() to null.\nif (value == null || value.equals(null)) {\n    return null;\n}\n\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Without the comment, someone might \"simplify\" the code or view it as a mysterious but essential incantation. Save future readers time and anxiety by writing down why the code is needed.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>A judgment call needs to be made as to whether code requires explanation. When learning Kotlin, I encountered code in an Android tutorial of the form:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>if (b == true)\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>I immediately wondered whether it could be replaced with:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>if (b)\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>as one would do in Java. After a little \u003Ca href=\"https://kotlinlang.org/docs/idioms.html#nullable-boolean\">research\u003C/a>, I learned that nullable Boolean variables are explicitly compared to true in order to avoid an ugly null check:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>if (b != null && b)\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>I recommend \u003Cem>not \u003C/em>including comments for common idioms unless writing a tutorial specifically for novices.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-6-provide-links-to-the-original-source-of-copied-code\">Rule 6: Provide links to the original source of copied code\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>If you're like most programmers, you sometimes use code that you find online. Including a reference to the source enables future readers to get the full context, such as:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:list -->\n\u003Cul>\u003Cli>what problem was being solved\u003C/li>\u003Cli>who provided the code\u003C/li>\u003Cli>why the solution is recommended\u003C/li>\u003Cli>what commenters thought of it\u003C/li>\u003Cli>whether it still works\u003C/li>\u003Cli>how it can be improved\u003C/li>\u003C/ul>\n\u003C!-- /wp:list -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>For example, consider this comment:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Following the link to the answer reveals:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:list -->\n\u003Cul>\u003Cli>The author of the code is Tomáš Procházka, who is in the top 3% on Stack Overflow.\u003C/li>\u003Cli>One commenter provides an optimization, already incorporated into the repo.\u003C/li>\u003Cli>Another commenter suggests a way to avoid an edge case.\u003C/li>\u003C/ul>\n\u003C!-- /wp:list -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Contrast it with this comment (slightly altered to protect the guilty):\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// Magical formula taken from a stackoverflow post, reputedly related to\n// human vision perception.\nreturn (int) (0.3 * red + 0.59 * green + 0.11 * blue);\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Anyone looking to understand this code is going to have to search for the formula. Pasting in the URL is much quicker than later finding the reference.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Some programmers may be reluctant to indicate that they did not write code themselves, but reusing code can be a smart move, saving time and giving you the benefit of more eyeballs. Of course, you should \u003Ca href=\"https://stackoverflow.blog/2019/11/26/copying-code-from-stack-overflow-you-might-be-spreading-security-vulnerabilities/\">never paste in code that you don't understand\u003C/a>.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>People \u003Ca href=\"https://stackoverflow.blog/2021/04/19/how-often-do-people-actually-copy-and-paste-from-stack-overflow-now-we-know/\">copy a lot of code\u003C/a> from Stack Overflow questions and answers. That code falls under Creative Commons licenses requiring attribution. A reference comment satisfies that requirement.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Similarly, you should reference tutorials that were helpful, so they can be found again and as thanks to their author:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html\n// for a great reference and examples.\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-7-include-links-to-external-references-where-they-will-be-most-helpful\">Rule 7: Include links to external references where they will be most helpful\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Of course, not all references are to Stack Overflow. Consider:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// http://tools.ietf.org/html/rfc4180 suggests that CSV lines\n// should be terminated by CRLF, hence the \\r\\n.\ncsvStringBuilder.append(\"\\r\\n\");\n\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Links to standards and other documentation can help readers understand the problem your code is solving. While this information may be somewhere in a design document, a well-placed comment gives readers the pointer when and where it is most needed. In this case, following the link indicates that RFC 4180 has been updated by RFC 7111—useful information.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-8-add-comments-when-fixing-bugs\">Rule 8: Add comments when fixing bugs\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Comments should be added not just when initially writing code but also when modifying it, especially fixing bugs. Consider this comment:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>  // NOTE: At least in Firefox 2, if the user drags outside of the browser window,\n  // mouse-move (and even mouse-down) events will not be received until\n  // the user drags back inside the window. A workaround for this issue\n  // exists in the implementation for onMouseLeave().\n  @Override\n  public void onMouseMove(Widget sender, int x, int y) { .. }\n\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Not only does the comment help the reader understand the code in the current and referenced methods, it is helpful for determining whether the code is still needed and how to test it.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>It can also be helpful to reference issue trackers:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// Use the name as the title if the properties did not include one (issue #1425)\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>While \u003Ccode>git blame\u003C/code> can be used to find the commit in which a line was added or modified, commit messages tend to be brief, and the most important change (e.g., fixing issue #1425) may not be part of the most recent commit (e.g., moving a method from one file to another).\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-rule-9-use-comments-to-mark-incomplete-implementations\">Rule 9: Use comments to mark incomplete implementations\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Sometimes it's necessary to check in code even though it has known limitations. While it can be tempting not to share known deficiencies in one's code, it is better to make these explicit, such as with a TODO comment:\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:code {\"className\":\"java\"} -->\n\u003Cpre class=\"wp-block-code java\">\u003Ccode>// TODO(hal): We are making the decimal separator be a period, \n// regardless of the locale of the phone. We need to think about \n// how to allow comma as decimal separator, which will require \n// updating number parsing and other places that transform numbers \n// to strings, such as FormatAsDecimal\n\u003C/code>\u003C/pre>\n\u003C!-- /wp:code -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Using a standard format for such comments helps with measuring and addressing technical debt. Better yet, add an issue to your tracker, and reference the issue in your comment.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-conclusion\">Conclusion\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>I hope the above examples have shown that comments don't excuse or fix bad code; they complement good code by providing a different type of information. As Stack Overflow co-founder Jeff Atwood has written, \"\u003Ca href=\"https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/\">Code Tells You How, Comments Tell You Why\u003C/a>.\" \u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Following these rules should save you and your teammates time and frustration. \u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>That said, I'm sure these rules aren't exhaustive and look forward to seeing suggested additions in (where else?) the comments.\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:heading -->\n\u003Ch2 id=\"h-memes-and-cartoons\">Memes and cartoons\u003C/h2>\n\u003C!-- /wp:heading -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>For your consideration...\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh4.googleusercontent.com/SJtgmtDmnQ4VHSZ--4tqlVp2gwd07meUHVxhHLTsxHdL9AYIXNqbYCMbCr7VYQgdKxqLFbS_BFoM-jEaN--E1D0mkFXqSPY9j6PcBZaHaVxp5nWHc2DC4WNFPfEAaZcdL8tnrENI\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Source: \u003Ca href=\"https://www.reddit.com/r/ProgrammerHumor/comments/8w54mx/code_comments_be_like/\">https://www.reddit.com/r/ProgrammerHumor/comments/8w54mx/code_comments_be_like/\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh3.googleusercontent.com/iE_eTsZPyEwWx-JacKGqqEH8IHtBf1qYcTynZCIVS1sgJgKpPZy77eyn7c5VGpT6-DSwXWGgc7HSpKLwEYR9CQ7HTbSfdQxvgqMUeEB7wqOEZ0d_rgzYh5FtHtoCTI1dTZuGGVKt\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Source: \u003Ca href=\"https://www.reddit.com/r/ProgrammerHumor/comments/bz35nh/whats_a_comment/\">https://www.reddit.com/r/ProgrammerHumor/comments/bz35nh/whats_a_comment/\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh6.googleusercontent.com/0eDsuR2I48vq1GRTywctu3Q44x_6Un7QkdeJaSrCwu64i1Tf42bzYwWF_NBuLrDZQ_-TNcVBIBBxUINmDrsinXkdfZ2knhcyCT6hm7awFzrgLl4y5L5xzArSx1-q_c0Mlqjmh13T\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh5.googleusercontent.com/rn1S8do8n_2FHFcM7wO7vZfHyZ2DUWP3ov33r30tjdxIuZiJFGKl80FHwaoYP1K4JygCDDTxs81Y7FrwUe_iD-K5yHVY14p-0mB9TfOsOoMV5RfnrItrO0wyVKEp-Dn0B-99jlI3\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Source: \u003Ca href=\"https://geekandpoke.typepad.com/geekandpoke/2011/06/code-commenting-made-easy.html\">https://geekandpoke.typepad.com/geekandpoke/2011/06/code-commenting-made-easy.html\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh5.googleusercontent.com/GVT2gs4CUkIulx7EJWbtosMzMrJ6Dl2ezh96I2gLK8-2KW1GmDYheQUW0hDavq2Tom02LICpN8Pe79OawCpmQky7C8hGhx7gBqepFTufFemBT7XacR5D7rchOxtEHlzbdBlxfMfz\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Ca href=\"https://geekandpoke.typepad.com/geekandpoke/2008/07/good-comments.html\">https://geekandpoke.typepad.com/geekandpoke/2008/07/good-comments.html\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh4.googleusercontent.com/TllexJNRx1YjUwxG41ZzTbFRpOjW1NeKwgtX_fdiztesW6sNrICIg3MVUFT3tCZ1lsWD4sUyZTF5EYWNoHv1rxBu2svEGBnQU7Q8xzxEBsxw6B99MW8RerLFVdD_1A3k6hkzyLlo\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>Source: \u003Ca href=\"https://www.commitstrip.com/en/2016/09/01/keep-it-simple-stupid/\">https://www.commitstrip.com/en/2016/09/01/keep-it-simple-stupid/\u003C/a>?\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh4.googleusercontent.com/faBPvUbSlSBk3ELYN3pDhe9rGibg5_ksNZqwah5Q8VF1W7RfD2RsHV3rJUVmzAb8akO3Blx_-UxWlPEFL98BPSBWqNvmpXA-EkIruV-B4YZ9JZTf02MlcgqjvC3eqFs8Znbv_Umh\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Ca href=\"https://www.commitstrip.com/en/2013/07/22/commentaire-de-commit/?\">https://www.commitstrip.com/en/2013/07/22/commentaire-de-commit/?\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh3.googleusercontent.com/EqbyuXuRESXB3lHuo1_5LGdzBZEEsnjsOtkPI-U9BuTL1k_gpnbdgVkv4CrB9xwh7e0upbFa6NjyOOLfPOHSAFssLoo4UOA_-uiex3Ykl7rcTxSC6f70BhH2bLjvsYrcH-MKM_Q_\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Ca href=\"https://geekandpoke.typepad.com/geekandpoke/2009/07/\">https://geekandpoke.typepad.com/geekandpoke/2009/07/\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->\n\n\u003C!-- wp:image -->\n\u003Cfigure class=\"wp-block-image\">\u003Cimg src=\"https://lh4.googleusercontent.com/-6lVtmBOSrMKuk9tjq_1xO65lo2TRis-iUCU71BdV7DFg4Aj0iuB1BrWPqeA2MZ_x23bSEvOFV9KWu-Tz0je-8nhMuO6fSiIL14FmnhITo34HR8UGLuQ6SEh-vvzWaC929ovkiDO\" alt=\"\"/>\u003C/figure>\n\u003C!-- /wp:image -->\n\n\u003C!-- wp:paragraph -->\n\u003Cp>\u003Ca href=\"https://geekandpoke.typepad.com/geekandpoke/2010/11/architecture.html\">https://geekandpoke.typepad.com/geekandpoke/2010/11/architecture.html\u003C/a>\u003C/p>\n\u003C!-- /wp:paragraph -->","html","2021-12-23T14:38:45.000Z",{"current":1078},"best-practices-for-writing-code-comments",[1080,1088],{"_createdAt":1081,"_id":1082,"_rev":1083,"_type":1084,"_updatedAt":1081,"slug":1085,"title":1087},"2023-05-23T16:43:21Z","wp-tagcat-code-for-a-living","9HpbCsT2tq0xwozQfkc4ih","blogTag",{"current":1086},"code-for-a-living","Code for a Living",{"_createdAt":1081,"_id":1089,"_rev":1083,"_type":1084,"_updatedAt":1081,"slug":1090,"title":1091},"wp-tagcat-comments",{"current":1091},"comments","Best practices for writing code comments",[1094,1100,1106,1112],{"_id":1095,"publishedAt":1096,"slug":1097,"sponsored":12,"title":1099},"28e560af-f0aa-4d46-bd90-f435ad604aa7","2026-06-26T14:00:27.102Z",{"_type":10,"current":1098},"paging-charity-how-can-engineering-leaders-avoid-becoming-bond-villains","Paging Charity! How can engineering leaders avoid becoming Bond villains?",{"_id":1101,"publishedAt":1102,"slug":1103,"sponsored":12,"title":1105},"4b22c2a3-3779-4966-93eb-5230391dbdce","2026-06-23T14:08:58.595Z",{"_type":10,"current":1104},"your-ai-shipped-a-backend-that-boots-that-is-the-whole-problem","Your AI shipped a backend that boots. That is the whole problem.",{"_id":1107,"publishedAt":1108,"slug":1109,"sponsored":12,"title":1111},"5cf362e1-fe7b-45af-b69c-914731c6a052","2026-06-23T14:00:00.000Z",{"_type":10,"current":1110},"the-2026-developer-survey-is-now-open-for-human-developers-only","The 2026 Developer Survey is now open (for human developers only)!",{"_id":1113,"publishedAt":1114,"slug":1115,"sponsored":12,"title":1117},"30b995f7-7cb9-4dd8-bf71-d0685940a32b","2026-06-19T14:00:00.000Z",{"_type":10,"current":1116},"dispatches-from-o-reilly-from-capabilities-to-responsibilities","Dispatches from O'Reilly: From capabilities to responsibilities",{"data":1119,"sourceMap":-1},{"count":1120,"lastTimestamp":1121},80,"2024-02-26T14:03:30Z"]