Skip to main content

Code Comments

The whole "no comments" thing can be taken too far. We should strive to write code that is clear as possible so comments aren't necessary.
However, the act of writing a function header before writing the function is a good way to think about the intent of the code your about to write.
If you try to write a concise description of a function and you struggle with it, then its a sign your design might be over complex,or you haven't decomposed the problem well enough.
Its also a good way to spot violations of SRP.if you find that you have to use the word "and" multiple times to describe the intent of a function, then you probably have multiple functions crammed Into one.
After refactoring your code, perhaps using TDD, if your comment is completely redundant because the code expresses everything you need to know, then as a last step you should delete the comment.
Here's what I consider bad comments:
1. Comments that add no value because the code already expresses intent more clearly than the comment.
2. Comments that are out of sync with the code.
3. Code block comments that would be better written as a function name.
Writing clean code takes discipline. The act of writing intent before the code helps you clarify in you mind the design, and is a valuable design tool.
The most valuable comments are ones that describe the why. Comments that describe the what are the dangerous kind.

Comments

  1. AdamMarch 20, 2015 at 7:58 PM

    Real world examples would be instructive here.

    ReplyDelete
  2. GuestApril 19, 2024 at 5:04 AM

    As the top window cleaning company in Coquitlam, we are proud to serve our fellow neighbors. That includes the residents and business in our community alike. Window Cleaning Specialists

    ReplyDelete

Post a Comment

Popular posts from this blog

Generating Java Mixed Mode Flame Graphs

Overview I've seen Brendan Gregg's talk on generating mixed-mode flame graphs  and I wanted to reproduce those flamegraphs for myself. Setting up the tools is a little bit of work, so I wanted to capture those steps. Check out the Java in Flames post on the Netflix blog for more information. I've created github repo ( github.com/jerometerry/perf )  that contains the scripts used to get this going, including a Vagrantfile, and JMeter Test Plan. Here's a flame graph I generated while applying load (via JMeter) to the basic arithmetic Tomcat sample application. All the green stacks are Java code, red stacks are kernel code, and yellow stacks are C++ code. The big green pile on the right is all the Tomcat Java code that's being run. Tools Here's the technologies I used (I'm writing this on a Mac). VirtualBox 5.1.12 Vagrant 1.9.1 bento/ubuntu-16.04 (kernel 4.4.0-38) Tomcat 7.0.68 JMeter 3.1 OpenJDK 8 1.8.111 linux-tools-4.4.0-38 linux-to...
235 comments
Read more

Basic Web Performance Testing With JMeter and Gatling

Introduction In this post I'll give a quick way to get some basic web performance metrics using both JMeter and Gatling . JMeter is a well known, open source, Java based tool for performance testing. It has a lot of features, and can be a little confusing at first. Scripts (aka Test Plans), are XML documents, edited using the JMeter GUI.  There are lots of options, supports a wide variety of protocols, and produces some OK looking graphs and reports. Gatling is a lesser known tool, but I really like it. It's a Scala based tool, with scripts written in a nice DSL. While the scripts require some basic Scala, they are fairly easy to understand and modify. The output is a nice looking, interactive, HTML page. Metrics   Below are the basic metrics gathered by both JMeter and Gatling . If you are just starting performance testing, these might be a good starting point . Response Time – Difference between time when request was sent and time when response has been fully re...
110 comments
Read more

Multi Threaded NUnit Tests

Recently I needed to reproduce an Entity Framework deadlock issue. The test needed to run in NUnit, and involved firing off two separate threads. The trouble is that in NUnit, exceptions in threads terminate the parent thread without failing the test. For example, here's a test that starts two threads: the first thread simply logs to the console, while the other thread turfs an exception. What I expected was that this test should fail. However, the test actually passes. readonly ThreadStart[] delegates = { () => { Console.WriteLine("Nothing to see here"); }, () => { throw new InvalidOperationException("Blow up"); } }; [Test] public void SimpleMultiThreading() { var threads = delegates.Select(d => new Thread(d)).ToList(); foreach (var t in threads) { t.Start(); } foreach (var t in threads) { t.Join(); } } Peter Provost posted an article that describes how to make this test fail. It...
139 comments
Read more