https://henrikwarne.com/2021/06/15/on-comments-in-code/ Henrik Warne's blog Thoughts on programming... Skip to content * Home * About [cropped-desk1] - 4 Things I Like About Microservices On Comments in Code Posted on June 15, 2021 | 1 Comment I used to think that I didn't need comments if I wrote self-documenting code. However, I have realized that I do write comments, and that I find them really useful. To see how many comments I write, and what kind they are, I wrote a script to analyze my git commits from the last six years. In total, seven percent of my committed lines contained a comment. This blog post has details on what constitutes good and bad comments, as well as more statistics from my script. Javadoc is mostly useless Part of the reason I was skeptical of comments was the prevalence of Javadoc-style comments. This style of commenting exists in other languages as well. Here is an example in Python that I just made up, but which is representative of this style: [python_doc] The problem with most of these comments is that they convey very little information. Often it is just a repetition of the method name and parameter names in a few more words. These comments may be useful for API:s exposed externally, but in an application where you have access to all the source code, they are mostly useless. If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does. These types of comment take up a lot of space without providing much value. Self-documenting code Instead of writing Javadoc comments, you are better off making the best possible use of method names and variable names. Each name you use can help explain what the computation is about and how it is done. One good reason for writing many small methods instead of one large method is that you have more places to use descriptive names, something I have written about here. When to comment Writing self-documenting code will get you a long way. However, there are times when having more information is useful. For example, the comment on the use of dialling zones in the code below: [java_comments] Here is another example: [reg_exp] Often the advice given is "Comment the Why, not the What". While this probably covers most of my comments, it is not how I think about when to comment. Instead, I tend to write a comment when there is something particularly tricky, either in the domain or in how the implementation is done. The standard advice from the "no comments are needed"-crowd (which I used to belong to) is to rewrite the code so you don't need to comment it. This is however not always possible. Sometimes the domain is just too complex. Sometimes the effort to rewrite the code would be too much compared to adding a comment. Another complaint about comments is that they will get out of sync with the code, thus hindering your understanding of the code rather than helping it. While this sometimes happens, it has not been a big problem for me. In almost all cases I analyzed, the comments were still valid. They have also been very useful. Every time I came across one of my comments like these, I was happy I wrote it. It doesn't take long to forget some of the details and nuances of the problem you are solving, and having the comment there with some extra context and explanation has been great. Logging as comments Sometimes you get a comment "for free" if you are logging an explanatory message. In the example below, the log statement explains what has happened, so there is no need for a comment. [log_as_com] Comment analysis When I first thought about checking how many comments all of my commits contained, I thought it would be enough with a one-liner like this to find the comments in all my Python commits (I only comment using #): git log --author=Henrik -p|grep '^+[^+]'|grep '#' | wc -l However, I soon realized that I wanted more details. I wanted to differentiate between end-of-line comments and whole line comments. I also wanted to find out how many "comment blocks" (consecutive lines of comments) I had. I also decided to exclude test files from the analysis. Plus, I want to be sure to exclude any commented-out code that happened to be there (there were unfortunately a few such cases). In the end I wrote a python-script to do the analysis. The input for the script was the output of git log --author=Henrik -p . From the output I saw that 1299 out of 17817 added lines of mine contained comments. There were 161 end-of-line comments, and 464 single line comments. The longest comment block was 11 lines, and there were 96 cases of comment blocks that had 3 or more consecutive lines. Conclusion I used to think that writing well-named functions would mean no comments were needed. However, looking at what I actually did, I noticed that I tended to add comments in tricky or unintuitive parts of the code. Every time I come back to those parts of the program, I am happy I made the effort to add a comment - they have been very helpful! Share this: * Twitter * Facebook * LinkedIn * Like this: Like Loading... Related This entry was posted in Programming and tagged comments. Bookmark the permalink. - 4 Things I Like About Microservices One response to "On Comments in Code" 1. [a96dd] Henrik Warne | June 15, 2021 at 9:56 pm | Reply Hacker News discussion: https://news.ycombinator.com/item?id= 27519445 Leave a Reply Cancel reply Enter your comment here... [ ] Fill in your details below or click an icon to log in: * * * * Gravatar Email (required) (Address never made public) [ ] Name (required) [ ] Website [ ] WordPress.com Logo You are commenting using your WordPress.com account. ( Log Out / Change ) Google photo You are commenting using your Google account. ( Log Out / Change ) Twitter picture You are commenting using your Twitter account. ( Log Out / Change ) Facebook photo You are commenting using your Facebook account. ( Log Out / Change ) Cancel Connecting to %s [ ] Notify me of new comments via email. [ ] Notify me of new posts via email. [Post Comment] [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ] * MOST POPULAR + Lessons Learned in Software Development + Top 5 Surprises When Starting Out as a Software Developer + Working as a Software Developer + Great Programmers Write Debuggable Code + What Makes a Good Programmer * RECENT POSTS + On Comments in Code + 4 Things I Like About Microservices + Recruiting Software Developers - Coding Tests + More Good Programming Quotes, Part 5 + 6 Small Unit Testing Tips + Mathematical Modelling of Football + Deployed To Production Is Not Enough + Good Logging + Working From Home - Cons and Pros + Artificial Intelligence - A Guide for Thinking Humans + 20.5 Years of XP and Agile + Secure by Design + More Good Programming Quotes, Part 4 + Grokking Deep Learning + EuroSTAR Testing Conference Prague 2019 + Classic Computer Science Problems in Python + When TDD Is Not a Good Fit + Recruiting Software Developers - Checking Out a Company + Book Review: Designing Data-Intensive Applications + Nordic Testing Days Tallinn 2019 + Book review: Accelerate + More Good Programming Quotes, Part 3 + Programming: Math or Writing? + Developer On Call + My Favorite Command-Line Shortcuts + 6 Git Aha Moments + Is Manual Testing Needed? + Exercises in Programming Style + Programming for Grade 8 + 6 Years of Thoughts on Programming + Benefits of Continuous Delivery + More Good Programming Quotes, Part 2 + Developer Testing + Programming Conference - QCon New York 2017 + Developers - Talk To People + Code Rot + Programmer Career Planning + Software Development and the Gig Economy + Book Review: The Effective Engineer + Things Programmers Say + Developer Book Club + Book Review: Release It! + 18 Lessons From 13 Years of Tricky Bugs + Learning From Your Bugs + More Good Programming Quotes + The Wisdom of Programming Quotes + Ph.D. or Professional Programmer? + Social Engineering from Kevin Mitnick + Recruiting Software Developers - Initial Contact + Coursera Course Review: Software Security + Lessons Learned in Software Development + Book Review: Clean Code + Coursera Course Review: Computational Investing Part 1 + Programmer Knowledge + 5 Reasons Why Software Developer is a Great Career Choice + A Response to "Why Most Unit Testing is Waste" + What Makes a Good Programmer? + Switching from Java to Python - First Impressions + Antifragility and Software Development + 5 Unit Testing Mistakes + Unit Testing Private Methods + A Bug, a Trace, a Test, a Twist + Session-based Logging + Finding Bugs: Debugger versus Logging + TDD, Unit Tests and the Passage of Time + Automatically Include Revision in Log Statement + 7 Ways More Methods Can Improve Your Program + LinkedIn - Good or Bad? + Great Programmers Write Debuggable Code + SET Card Game Variation - Complementary Pairs + Programmer Productivity - Interruptions, Meetings and Working Remotely + What Do Programmers Want? + Coursera course review: Algorithms: Design and Analysis, Part 2 + Blog stats for 2012 (by WordPress) + Working as a Software Developer + 4 Reasons Why Bugs Are Good For You + Book Review: How Google Tests Software + Top 5 Surprises When Starting Out as a Software Developer + Programmer Productivity: Emacs versus IntelliJ IDEA + Why I Love Coding + Coursera course review: Design and Analysis of Algorithms I + Mac OS X Break Programs Review + Favorite Programming Quotes + How I Beat Repetitive Stress Injury + Introduction to Databases - On-line Learning Done Well + 10 million SET games simulated using "Random among 'most similar' Sets" + 10 million SET games simulated using "Random among available Sets" + 10 million SET games simulated using "First found Set" + SET(r) Probabilities Revisited * TAG CLOUD algorithms book book review break program bugs career code coding conference coursera creativity databases debugging DevOps emacs ergonomics face to face Google hiring ide idea integration testing intellij interruption job knowledge learning linkedin logging love machine learning Mac OS X meeting meta methods office on-line course probabilities production software productivity professional software development programmer programming programming course programming job python quotes recruiting refactoring Repetitive Stress Injury review revision RSI security session-based SET game simulation software development statistics stats stretches subversion surprises svn tdd test-driven development testing time trouble-shooting unit-test unit testing university version work working * RSS + RSS - Posts + RSS - Comments * Follow Blog via Email Enter your email address to follow this blog and receive notifications of new posts by email. Join 323 other followers Email Address: [ ] Follow Blog at WordPress.com. Write a Comment... [ ] Email (Required) [ ] Name (Required) [ ] Website [ ] [Post Comment] Loading Comments... Comment x [Close and accept] Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use. To find out more, including how to control cookies, see here: Cookie Policy %d bloggers like this: [b]