# code comments Published articles for code comments. This is one page of public article previews, not the complete archive. Follow Next page to continue. Summaries are not the original full articles. ## Code Review Responses: Add Context When It Counts DevFeed: [Code Review Responses: Add Context When It Counts]() Original publisher: [Read original article]() Author: Google Testing Bloggers (noreply@blogger.com) Published: 2026-05-12T12:30:00Z Content type: tutorial Language: en Sources: [Google Testing Blog]() Topics: [Code review](), [context](), [engineering-culture]() Tags: [code-comments](), [code-review](), [context](), [saicharan-nimmala](), [test](), [tott]() ### AI overview This Google Tech on the Toilet article explains that code review responses should include brief context when a code change or discussion does not make the resolution obvious. It gives examples involving edge-case tests, design trade-offs, and offline discussions. ### Source excerpt This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office. By Saicharan Nimmala When responding to code review comments, responses like "Done," "Updated," or "Fixed" are commonly used to indicate addressing a suggestion. However, sometimes, a little extra context adds a lot of clarity. Next time you resolve a code review comment, ask yourself: "Is how I addressed the comment completely obvious from the code change and comment thread?" If not, supplement your response with a brief note to clarify the "why" or "how." Your reviewers will thank you. When is it helpful to add context to a code review comment response? Here are a few examples: Your code change doesn't fully explain how you addressed the comment. Providing a brief summary helps the reviewer verify the changes without re-examining every line of the delta, and creates a clearer historical record. Reviewer: This approach seems risky. It might not handle all the edge cases properly. Less helpful response: More helpful response: Author: Updated. Good catch. I've added checks for null, empty, and negative inputs, each with a new test case. Thanks! You made a design choice or trade-off that isn't self-evident. Capturing the reasoning behind a choice provides valuable context. Note that non-obvious design choices within the code should ideally be explained in code comments or the commit description as well. Reviewer: Consider using a more performant library for this data transformation. Less helpful response: More helpful response: Author: I'll go with Y. Done. I considered Library X, but stuck with Library Y because our datasets here are typically small, so the performance difference is negligible, and Library Y has a much simpler API. An offline discussion influenced the solution. Briefly summarizing the outcome or key reasoning from an offline sync ensures that other reviewers, who only see the final code ## Using LLMs to Evaluate Code Interpretability Instead of Maintaining Comments DevFeed: [Using LLMs to Evaluate Code Interpretability Instead of Maintaining Comments]() Original publisher: [Read original article]() Author: Yegor Bugayenko (yegor256@gmail.com) Published: 2026-01-10T21:00:00Z Content type: opinion Language: en Sources: [Yegor Bugayenko]() Topics: [Large Language Model](), [code comments](), [Documentation](), [Software Engineering](), [trust]() Tags: [code-comments](), [code-documentation](), [code-interpretability](), [documentation](), [llm-code-analysis](), [llms](), [quality](), [self-documenting-code](), [software-engineering]() ### AI overview The article argues that manually maintained code comments can become unclear or outdated. It proposes using LLMs to explain code on demand and introducing a Code Interpretability Score that can fail the build when code is too difficult for the model to explain. ### Source excerpt Instead of writing code comments that decay and mislead, let LLMs generate documentation on-demand and fail the build when code is too obscure for them to explain. ## A critique of software complexity, dependencies, and rapid development practices DevFeed: [A critique of software complexity, dependencies, and rapid development practices]() Original publisher: [Read original article]() Published: 2025-02-08T14:47:49Z Content type: opinion Language: en Sources: [Antirez]() Topics: [Software](), [Code](), [coding](), [Framework](), [systems]() Tags: [code](), [code-comments](), [compatibility](), [complexity](), [dependencies](), [framework](), [language](), [software](), [systems]() ### AI overview The article argues that software quality and the joy of hacking are harmed by excessive complexity, bloated dependency chains, poor backward API compatibility, unnecessary rewrites, frequent shifts in languages and frameworks, and prioritizing speed over thoughtful design. ### Source excerpt We are destroying software by no longer taking complexity into account when adding features or optimizing some dimension. We are destroying software with complex build systems. We are destroying software with an absurd chain of dependencies, making everything bloated and fragile. We are destroying software telling new programmers: "Don't reinvent the wheel!". But, reinventing the wheel is how you learn how things work, and is the first step to make new, different wheels. We are destroying software by no longer caring about backward APIs compatibility. We are destroying software pushing for rewrites of things that work. We are destroying software by jumping on every new language, paradigm, and framework. We are destroying software by always underestimating how hard it is to work with existing complex libraries VS creating our stuff. We are destroying software by always thinking that the de-facto standard for XYZ is better than what we can do, tailored specifically for our use case. We are destroying software claiming that code comments are useless. We are destroying software mistaking it for a purely engineering discipline. We are destroying software by making systems that no longer scale down: simple things should be simple to accomplish, in any system. We are destroying software trying to produce code as fast as possible, not as well designed as possible. We are destroying software, and what will be left will no longer give us the joy of hacking. Comments ## Generative AI and the Reverse Baltimore Phenomenon DevFeed: [Generative AI and the Reverse Baltimore Phenomenon]() Original publisher: [Read original article]() Author: Peter Lawrey (noreply@blogger.com) Published: 2025-01-08T13:08:00Z Content type: opinion Language: en Sources: [Vanilla Java]() Topics: [Artificial Intelligence](), [Documentation](), [Generative AI](), [code comments](), [context]() Tags: [ai](), [code-comments](), [context](), [documentation](), [generative-ai](), [opinion]() ### AI overview The article introduces the Reverse Baltimore Phenomenon as an analogy for a tendency in generative AI-generated documentation and code comments. With limited context, AI may fill gaps with authoritative-sounding but unnecessary details, creating a misleading sense of completeness. The article argues that useful documentation should provide enough explanation without overwhelming readers. ### Source excerpt One of the first challenges developers might face is getting generative AI to produce accurate documentation. Once you are comfortable doing this, the next challenge is creating enough documentation to be helpful without overwhelming the reader. Until generative AI came along, it might have seemed like there could never be too much documentation. Now, the challenge is to provide just enough detail to give understanding without overwhelming the material with unnecessary details. I was exploring the best way to generate accurate documentation for a project as I was flying over Australia and saw Alice Springs on the map, and it reminded me of the Reverse Baltimore Phenomenon. Generating documentation can give a "sense of completeness" that will likely be a distraction rather than have practical value. The text produced by a generative AI system can superficially convincingly feel "whole", but much of it is fluff that isn't actually helpful to the reader or an AI using it as instructions. e.g. copilot or a chat app. The Reverse Baltimore Phenomenon describes how small but isolated towns (like Alice Springs) can appear on a zoomed-out map while much larger cities elsewhere remain unlabeled. They appear because, in a sparsely populated area, the cartographer (or map algorithm) has "room" for that single label--despite far bigger cities in denser regions that don't make it onto the map. Generative AI exhibits a similar dynamic with documentation and code comments: in an attempt to be thorough, it sometimes fills "empty space" with details that don't truly matter. Much like Alice Springs popping up on world maps simply because there's little else around, AI-generated documentation can insert seemingly authoritative but superfluous commentary simply because there's room to elaborate. Both phenomena stem from "filling a void": Sparse vs. Dense Spaces Cartography: Sparse regions allow tiny towns to receive disproportionate emphasis. AI Text Generation: Minimal context leads the ## Less Is More: Principles for Simple Comments DevFeed: [Less Is More: Principles for Simple Comments]() Original publisher: [Read original article]() Author: Google Testing Bloggers (noreply@blogger.com) Published: 2024-08-21T12:38:00Z Content type: article Language: en Sources: [Google Testing Blog]() Topics: [Code](), [Documentation](), [Testing]() Tags: [code](), [code-comments](), [code-health](), [cognitive-load](), [david-bendory](), [improvements](), [reduce](), [tott](), [writing]() ### AI overview This article presents principles for writing simple, maintainable code comments. It recommends reviewing comments separately from code, making them self-contained, including only essential information, and using links to bugs or documentation for follow-up context. ### Source excerpt This is another post in our Code Health series. A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office. By David Bendory Simplicity is the ultimate sophistication. -- Leonardo da Vinci You're staring at a wall of code resembling a Gordian knot of Klingon. What's making it worse? A sea of code comments so long that you'd need a bathroom break just to read them all! Let's fix that. Adopt the mindset of someone unfamiliar with the project to ensure simplicity. One approach is to separate the process of writing your comments from reviewing them; proofreading your comments without code context in mind helps ensure they are clear and concise for future readers. Use self-contained comments to clearly convey intent without relying on the surrounding code for context. If you need to read the code to understand the comment, you've got it backwards! Not self-contained; requires reading the code Suggested alternative // Respond to flashing lights in // rearview mirror. // Pull over for police and/or yield to // emergency vehicles. while flashing_lights_in_rearview_mirror() { if !move_to_slower_lane() { stop_on_shoulder(); } } Include only essential information in the comments and leverage external references to reduce cognitive load on the reader. For comments suggesting improvements, links to relevant bugs or docs keep comments concise while providing a path for follow-up. Note that linked docs may be inaccessible, so use judgment in deciding how much context to include directly in the comments. Too much potential improvement in the comment Suggested alternative // The local bus offers good average- // case performance. Consider using // the subway which may be faster // depending on factors like time of // day, weather, etc. // TODO: Consider various factors to // present the best transit option. // See issuetracker.fake/bus-vs-subway commute_by_lo ## Documentation Has Different Meanings and Requires Context-Specific Practices DevFeed: [Documentation Has Different Meanings and Requires Context-Specific Practices]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2023-10-17T07:00:00Z Content type: opinion Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [Development](), [code comments](), [API](), [Markdown](), [toolchain]() Tags: [api](), [best-practices](), [blog](), [code-comments](), [documentation](), [markdown](), [technical-documentation](), [toolchain]() ### AI overview The article argues that "documentation" can refer to different materials, from README files and code comments to developer portals, manuals, and API references. Because these forms serve different audiences and contexts, advice to reduce or replace documentation with automation cannot be applied universally. ### Source excerpt There was a post submitted to the Orange Website™ the other week with the title "Delete half your documentation" (HN thread here). The author talks about how documentation inherently has a cost, and how we should minimize the amount of documentation we need. It becomes outdated, requires maintenance, and "nobody reads it anyway". Instead, they argue, we should use type annotations, tested examples, and other methods to remove the requirement for manually maintaining documentation. Some of these arguments have some merits in the right context. But what really caught my eye in the post was this line: "When I say 'documentation', I mean all forms of it, including README, Markdown files, docstrings, and code comments." Hang on. This is not all forms of documentation! And we certainly cannot apply these rules universally. Documentation is in the eyes of the reader I recently Tweeted about the confusion that can happen when people use the word "documentation" to refer to different things. The word "documentation" has so many meanings depending on who you're talking to. To one person it's a single README file. To another, it's a full blown dev portal with guides and API references. Causes legitimate confusion sometimes -- Niklas Begley (@NiklasBegley) September 6, 2023 The post mentioned above is a great example of this phenomenon. The author clearly had the view that "documentation" means code documentation: docstrings, and other supplementing information you can include in or generate from raw source code. This is quite natural for software developers, since it's the kind of documentation they are used to producing themselves. And for their case, perhaps relying on automation over prose to ensure your documentation is in order is a good idea. But what about developer portals, manuals, or API references? Surely a technical writer documenting a complex developer toolchain should not apply the same thinking and "delete half their documentation"? An overloaded term Technical ## Writing testable examples in Go DevFeed: [Writing testable examples in Go]() Original publisher: [Read original article]() Published: 2023-01-12T00:00:00Z Content type: tutorial Language: en Sources: [William Kennedy]() Topics: [Go Language](), [Documentation](), [Code](), [test]() Tags: [code-comments](), [documentation](), [examples](), [generate-documentation](), [go](), [golang](), [syntax](), [test](), [testable-examples](), [toolchain]() ### AI overview This video tutorial explains how to write testable examples in Go documentation. It covers Go's documentation comments, special comment syntax for formatting, and test functions that produce code samples users can run. ### Source excerpt Introduction Google developed Go to be an alternative to C++ with the internet and scale in mind. Go's toolchain automates tasks that are easily overlooked, and amongst those tasks is generating documentation. Go has the ability to generate documentation based on comments written in your source code. As the end user, you have the choice to view this documentation in your terminal or, if your code is publicly accessible, on pkg.go.dev. Go also offers special comment syntax to further format and style the generated documentation. ## Better Code Review: Part One DevFeed: [Better Code Review: Part One]() Original publisher: [Read original article]() Author: Molly King Published: 2018-11-26T17:15:14Z Content type: tutorial Language: en Sources: [RetailMeNot]() Topics: [Code review](), [Software Engineering](), [Pull Request](), [Code]() Tags: [bugs](), [code-comments](), [code-review](), [pull-request](), [review](), [software-development](), [software-engineering](), [tips]() ### AI overview This first article in a three-part series presents self-review as preparation for code review. It recommends running, reading, and documenting code before opening a pull request, arguing that this can catch bugs earlier and support more productive technical discussions. ### Source excerpt Self-Review Code reviews are an integral part of software engineering, and unless you work alone, are likely to be a regular part of your work life in building software products. Code reviews can occasionally be contentious, and about as fun as a root canal, but they don't have to be! Over the course of this three-part blog series, I will present some tips from my experience to help you review code and for your code to be reviewed in a more productive and less onerous way. First, by putting your code through a form of self-review before having it reviewed by others, you can catch bugs earlier and set yourself up for more successful technical discussions. Microsoft conducted an internal study on code review in 2013. Their aim was to find out why we do code reviews, what the most frequent outcomes are, and how we can conduct reviews more effectively. While most of those surveyed listed finding bugs as their main motivation for code review, in practice only 14% of code comments centered around code defects. The main outcomes found in the study were knowledge transfer, increased team awareness, and finding alternative solutions to problems. Given this information, how can we as reviewers and reviewees change our approach to help bolster those outcomes? The code review process does not begin when you open a pull request (PR). It begins when you start writing code that you intend to merge to a shared codebase. There is a level of due diligence that we are obligated to perform before opening that PR to ensure the best process for everyone involved. I believe by engaging in a few steps of self-review before opening a PR, we can all produce better, more robust code. I propose that there are three steps to self-review: Run it Read it Document it Run it This may sound obvious, but run your code. Even in the case of a simple String change, always run your code. Crashing code that goes to code review creates unnecessary churn and wastes developer and QE time. Very well-written c ## A Philosophy of Software Design DevFeed: [A Philosophy of Software Design]() Original publisher: [Read original article]() Published: 2018-10-18T10:07:35Z Content type: opinion Language: en Sources: [Bert Hubert's writings]() Topics: [Software Engineering](), [Programming](), [Architecture & Design](), [Software]() Tags: [book-review](), [books](), [code-comments](), [complexity](), [kernel](), [philosophy](), [programming](), [software-design](), [software-development]() ### AI overview A review of John Ousterhout's book A Philosophy of Software Design, which distills decades of programming and language-development experience into practical ideas for managing software complexity. The review highlights concepts such as shallow and deep methods, information leakage, error prevention, and the role of source-code comments. ### Source excerpt John Ousterhout, of TCL fame, has written a book that is as small (literally) as it is important. Weighing in at 178 none too big pages, it takes us on an inspired trip through what John has learned over the decades. There is no shortage of thought on programming. There is also no shortage of people doing programming. What is rare however is a compendium of mature insights from someone that clearly still is into programming. ## Writing system software: code comments. DevFeed: [Writing system software: code comments.]() Original publisher: [Read original article]() Published: 2018-10-06T20:08:58Z Content type: opinion Language: en Sources: [Antirez]() Topics: [Code](), [Redis](), [debugging](), [Lua]() Tags: [code](), [code-comments](), [cognitive-load](), [debugging](), [opinion](), [redis]() ### AI overview The article analyzes comments in the Redis source code and argues that comments are important for maintainability, debugging, and understanding code. It emphasizes that comments can explain why code takes a particular approach and reduce the cognitive load on readers. ### Source excerpt For quite some time I've wanted to record a new video talking about code comments for my "writing system software" series on YouTube. However, after giving it some thought, I realized that the topic was better suited for a blog post, so here we are. In this post I analyze Redis comments, trying to categorize them. Along the way I try to show why, in my opinion, writing comments is of paramount importance in order to produce good code, that is maintainable in the long run and understandable by others and by the authors during modifications and debugging activities. Not everybody thinks likewise. Many believe that comments are useless if the code is solid enough. The idea is that when everything is well designed, the code itself documents what the code is doing, hence code comments are superfluous. I disagree with that vision for two main reasons: 1. Many comments don't explain what the code is doing. They explain what you can't understand just from what the code does. Often this missing information is *why* the code is doing a certain action, or why it's doing something that is clear instead of something else that would feel more natural. 2. While it is not generally useful to document, line by line, what the code is doing, because it is understandable just by reading it, a key goal in writing readable code is to lower the amount of effort and the number of details the reader should take into her or his head while reading some code. So comments can be, for me, a tool for lowering the cognitive load of the reader. The following code snippet is a good example of the second point above. Note that all the code snippets in this blog post are obtained from the Redis source code. Every code snipped is presented prefixed by the file name it was extracted from. The branch used is the current "unstable" with hash 32e0d237. scripting.c: /* Initial Stack: array */ lua_getglobal(lua,"table"); lua_pushstring(lua,"sort"); lua_gettable(lua,-2); /* Stack: array, table, table.sort */