# Shiva Garg

Published articles for Shiva Garg.

This is one page of public article previews, not the complete archive. Follow Next page to continue. Summaries are not the original full articles.

## How to Write Code Comments That Improve Readability

DevFeed: [How to Write Code Comments That Improve Readability](<https://devfeed.tech/articles/let-code-speak-for-itself-23849.md>)

Original publisher: [Read original article](<http://testing.googleblog.com/2023/12/let-code-speak-for-itself.html>)

Author: Google Testing Bloggers (noreply@blogger.com)

Published: 2023-12-12T16:06:00Z

Content type: tutorial

Language: en

Sources: [Google Testing Blog](<https://devfeed.tech/sources/google-testing-blog.md>)

Topics: [Code](<https://devfeed.tech/topics/code.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>), [implementation](<https://devfeed.tech/topics/implementation.md>)

Tags: [api-documentation](<https://devfeed.tech/tags/api-documentation.md>), [code](<https://devfeed.tech/tags/code.md>), [code-health](<https://devfeed.tech/tags/code-health.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [francois-aube](<https://devfeed.tech/tags/francois-aube.md>), [guide](<https://devfeed.tech/tags/guide.md>), [readability](<https://devfeed.tech/tags/readability.md>), [shiva-garg](<https://devfeed.tech/tags/shiva-garg.md>), [tott](<https://devfeed.tech/tags/tott.md>)

### AI overview

The article offers practical guidance for writing maintainable code: use comments to explain why an approach is taken, choose descriptive identifiers, document function purpose and meaning, and avoid comments about implementation details that may change.

### 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 Shiva Garg and Francois Aube Comments can be invaluable for understanding and maintaining a code base. But excessive comments in code can become unhelpful clutter full of extraneous and/or outdated detail. Comments that offer useless (or worse, obsolete) information hurt readability. Here are some tips to let your code speak for itself: Write comments to explain the "why" behind a certain approach in code. The comment below has two good reasons to exist: documenting non-obvious behavior and answering a question that a reader is likely to have (i.e. why doesn't this code render directly on the screen?): // Eliminate flickering by rendering the next frame off-screen and swapping into the // visible buffer. RenderOffScreen(); SwapBuffers(); Use well-named identifiers to guide the reader and reduce the need for comments: // Payout should not happen if the user is // in an ineligible country. std::unordered_set<std::string> ineligible = {"Atlantis", "Utopia"}; if (!ineligible.contains(country)) { Payout(user.user_id); } if (IsCountryEligibleForPayout(country)) { Payout(user.user_id); } Write function comments (a.k.a. API documentation) that describe intended meaning and purpose, not implementation details. Choose unambiguous function signatures that callers can use without reading any documentation. Don't explain inner details that could change without affecting the contract with the caller: // Reads an input string containing either a // number of milliseconds since epoch or an // ISO 8601 date and time. Invokes the // Sole, Laces, and ToeCap APIs, then // returns an object representing the Shoe // available then or nullptr if none were. Shoe* ModelAvailableAt(char* time); // Returns the Shoe that was available for // purchase at `time`