I’m often asked about comments in code: when to do it, how to do it, what to put, etc. I’ve recently run into Steve’s post about when to comment your code, left a comment (!) there, and we got to expand our conversation in his podcast/screencast (link at the bottom). I’ve decided to create this post to consolidate the links and info shared during the interview, to make it easy for folks to find the material.

I remembered writing blog posts a couple of times over the years and it’s interesting to see how my opinion on this subject has changed over time.

The first post goes all the way back to 2005, with me asking “can you plesae put some comment on that Regular Expression?”. 15 years later, I still ask my smart friends to get me the RegEx I need, along some comments as to what each piece does!

In 2007, I was big into using Xml Comments, GhostDoct, and Documentor… I’m not anymore, as documented 10 years later with my post “XmlDoc Comments: Auto Generate and Hide the Clutter”. In nutshell, if we’re documenting a public API, yes, by all means let’s put in that documentation, but making it count: commenting the GetCustomers endpoint with “Gets the customers” doesn’t add any value to the effort!

My practice of making comments stick out as a sore thumb posted in 2010 still stands in 2020: I still set up all of my IDEs in that manner and it still produces exactly the outcome as I intended.

When I do want to drop a quick TODO comments in code (watch/listen to the podcast interview when it’s up to know why I might do that), I have templates on my IDEs to automate that: ReSharper in Visual Studio, User Snippet in VS Code, Live Template in RubyMine.

In regards to code that’s commented out, like so:

We should be using a source control system; if we ever want that code back, we have a way to bring it back. So just remove it!

Still using the example above, notice that each if-block is preceeded by a comment. Is it really necessary? How about removing the comment and extracting the expression into a method that tells us the question being asked?

There’s also the “narrator-style” comment:

Narrating every single line of code is very annoying (by the way, I think I wrote the code above many moons ago). If the comments were written initially as a placeholder for the steps that needed to be implemented, let’s make sure to get rid of it when we’re done.

Last but not least, some people say (I’ve said it myself) that comments should document “why” the code was written in such manner. I’d propose a variaton to that: how about documenting the why with some good specs (or tests, if that’s how you prefer)?

Now, I’m not refering to tests that look like this:

Such test doesn’t tell us the “why”; it tells us the “how”. I mean this kind of test (now you’ll see why spec fits better):

Summing it up, this is how I prefer to “comment” code:

• Given-When-Then specs
• Writing code English-first

If I do have a real need to drop an actual comment in code (“why do we have this query in the code that has to potential to perform badly”), I’ll probably drop a quick comment, with a link out to the issue tracker, where I’ll put more context about why the code was left like that, and where a Product Owner can decide when it’s appropriate to address the situation.

Any comments? 🙂

And for audio-only version:

https://www.weeklydevtips.com/episodes/code-comments-with-guest-claudio-lassala

I mentioned how eager status code analysis is awful. A policy that forces developers to put XmlDoc comments is a good example of that.

This is how I see it: as I think through how I want to implement something I create an interface (created off tests I just wrote). The code might look something like this…

Right off the bat, VS is already showing me squigglies on the code I just wrote. I hover over it and this is what I see:

Right now I can’t even compile the code, and I don’t feel like typing Xml comments because I’m still thinking through my design and implementation. Parts of this interface are likely to be changed very quick, and any sort of documentation will become useless.

Since I need to conform with this policy, I use GhostDoc to just spit out the comments:

At this point I don’t really care whether the auto-generate comments make sense or not; I’m just satisfying what’s required in this development environment setup so I can get my immediate work done.

Of course, now what used to take just under 10 lines of code cannot even fit on my screen anymore and it requires scrolling!! That’s unacceptable to me. I can’t quite function seeing so much clutter! Fortunately, I’ve found this NoComment extension, which gets those comments out of my sight:

Now I can actually focus on what’s really important. Later, when I’m done with my design and implementation, then, and only then, I can review those Xml Comments prior to committing the work to the central source control repository.

The other day I was pairing with my buddy and co-worker Alan Stevens. We were reviewing some code, and at one point he said: “Claudio, those comments are ugly!”. At first I thought he meant how comments were worded, but then I realized he meant the way the comments were formatted:

You can see in the snapshot above that something really stands out, right?

Comments (which include code that’s commented out, but *not* XML Comments) are formatted in my environment in a very nasty way, and that’s on purpose. The thing is so ugly, it forces me to read it and find out what it’s all about:

• It may be a TODO, so I want to make sure it won’t be forgotten (very often, a TODO is dropped in code to indicate some Technical Debt);
• It may be code that’s commented out that should have been removed in the first place, instead of be sitting there as waste, polluting our code base with useless, distracting things. “But what if we ever need that code back?”, one might ask. Well, hello-oh, it’s 2010; people better be using some sort of Source Control System!!
• It may be the means of a developer to explain some poorly written code; most times a simple “rename variable” or “extract method” refactoring can easily remove the need of the crappy comment;
• In very rare situations, the comment is actually useful in explaining the intent of the code, so it’s a good thing that it stands out.

It comes a time when code may be tainted with so much useless comment that the mind just starts to ignore the warnings. What do I do? Just change the coloring to some other new ugly combination. 

How about you: do you have similar approach regarding how you see comments in the code? Do you configure your environment so to have the editor visually indicate anything you deem important?

Just wrapped up a book club on Head First Design Patterns (HFDP). Here’s a summary of what I shared at our Lightning Talks.

I read the “Gang of Four” (GoF) book, “Design Patterns: Elements of Reusable Object-Oriented Software“, in the early 2000s. That was a tough read for me; very dense, and hard to relate to. Good book, but not what I needed at the time.

Then ran into the 1st edition of HFDP in 2005:

I loved the way the book taught the concepts, using a good mix of analogies with real-world things I can immediately relate to, principles, and some code in between. I’ve been recommending that book to whoever asked, and wanted to revisit it to see how well it aged.

For the book club, we picked up the 2nd edition, published in 2021:

As with the 1st edition, all the source code is Java, which I’ve never worked with. But that doesn’t matter because the code is there only to give examples of the concepts (the most important thing) explained. The knowledge acquired is transferrable.

With that said, there was one chapter that I think spent too much time explaining some very specific aspects of Java, but that didn’t affect my enjoyment of the book, as I could visualize its counterpart in .NET. I do see that section being a little harder to grasp for developers who may solely focus on the frontend, though.

Going through the book this 2nd time, I realized that when I read it the first time I still didn’t know about the SOLID principles; that I learned a couple of years later. This time, I noticed I was anticipating where they were going with some explanation, and eventually, they’d drop in things like “Dependency Inversion Principle”. While the book calls out DIP, it never mentions SOLID. I can’t recall if the 1st edition mentioned anything related to SOLID at all. Anyway, I enjoy learning in a spiral, and it was good to revisit the content from this perspective of having acquired more knowledge and experiences over the years.

Speaking of experiences, the book club had a good mix of previous experiences; some members already had a lot, others were just getting started, some had more experience with backend than frontend development, some had more with functional programming than object-oriented programming languages. It all added to our having great conversations.

Here are some of my key takeaways…

Principles

The book does a good job at sharing not just patterns, but also principles, which help us understand better why certain patterns exist. Here are a few examples of principles that were brought up:

Program to an interface, not an implementation

That’s the D in SOLID: Dependency Inversion Principle, or DIP, already mentioned earlier.

Favor composition over inheritance

I first learned OOP in Visual FoxPro in a very inheritance-heavy way. It took me a while to understand and internalize why I should favor composition over inheritance.

This is what made the lightbulb go off for me:

Swapping behaviors with inheritance is done at compile time.
Swapping behaviors with composition is done at run time.

There are other things to consider, such as composition making it easier to follow the Single Responsibility Principle, but understanding the power it brings to run time behavior is huge.

Principle of Least Knowledge

Aka Law of Demeter, I kind of like Principle of Least Knowledge better.

For a common example, let’s try this one:

cart.Items.Add(product)

The code above doesn’t do things to the cart; it does to the cart’s Items property. Is that a list, a collection, or what? That’s excessive information. How about this version, instead?

cart.AddItem(product)

That way, the code only knows of the cart and it adds a product to it; how it stores the items is none of our business.

A simplistic way to think about it: too many dots reaching into an object means bad!

Patterns

The book covers one pattern per chapter, including Strategy, Observer, Decorator, Factory, and Command.

There’s a chapter on Compound Patterns, more specifically, Model-View-Controller (MVC). That one mentions other patterns that are often part of MVC: decorator, adapter, abstract factory, observer, strategy, composite, and iterator.

The very last chapter lists “leftover” patterns (about 10 of them). What was interesting to me is that there are a few patterns that would probably not be considered leftovers if the book was focused on .NET, such as Mediator, Builder, and Chain of Responsibility.

OOP vs FP

I’ve been seeing a number of people putting OOP down in favor of Functional Programming, steering away from content on design patterns because “that’s what the old folks do”. Why not leverage both?

Take as an example this snippet that uses the Command pattern:

That’s the OO way of implementing it, with classes, methods, and interfaces. Since the Do method takes in an ICommand interface, that parameter could also be wrapped in a decorator(s) or adapter, implemented as different strategies or created by factories, etc.

One could argue that if the ICommand interface only has one method, Execute, it could be replaced by a function, represented in the snippet below as an Action:

Action is a delegate, which in C# is an object that represents a reference to a method (or function). Those can also be created by factories, wrapped in decorators, etc. So we’re in OO land, but approaching it with a functional perspective.

When working in functional languages, one can also leverage knowing design patterns, and their intent, and then consider whether they’d be appropriate in solving a problem there. Concepts such as commands, adapters, proxies, and factories, are out there and may come in handy, regardless of language, syntax, you name it.

Patterns in life

I like how the book uses things from life, such as restaurant menus and TV remotes, to explain the concepts.

It’s a fun exercise to look at other things around us and how they relate to some patterns.

Take this image as an example:

The plug and the outlet work together based on agreed interfaces; the outlet sees the plug, and the plug sees the outlet.

What if we want to put a timer to shut off the outlet after a certain time? We use something like this…

Or we could also use something like this:

Heck, we could even use both. The plug and the outlet wouldn’t care; they wouldn’t even know those decorators were there.

What if the plug and the outlet conform to different interfaces (standards)? We use an adapter (but we can also still use those decorators)!

Anti-Patterns

I really like how the book defines anti-patterns:

An Anti-Pattern tells you how to go from a problem to a BAD solution.

Shared Vocabulary

One of the main reasons to learn design patterns is to build a shared vocabulary; we can condense full sentences, paragraphs, and long explanations, down to a single word. That is, as long as everybody in the room knows what that pattern is! If people aren’t familiar with it, that’s an opportunity to learn and grow together.

I like the book’s list of great places to leverage the shared vocabulary:

1. In design meetings
2. With other developers
3. In architecture documentation
4. In code comments and naming conventions
5. To groups of interested developers

Zen mind is a Beginner mind

Do not let all that pattern knowledge overly influence design decisions.

Yup, always go with the simplest solution. Let patterns emerge.

Take a deep breath, open up your mouth, and say it out loud in a full voice: “You are doing it wrong!”

You’ve done that before, right? I know I have. Once we know something (or think we do), it’s very easy to say someone is doing it wrong. Software developers do that. A lot.

• “Wow, you’re using this library instead of that library? You’re doing it wrong!” 
• “You’re using this pattern instead of that pattern? You’re doing it wrong!”,
• “You’re writing a blog post instead of writing code…” You got the idea.

Once upon a time, I used to put comments in code everywhere. My current self could visit my past self and say “you’re doing it wrong!” about commenting code.

Whatever it is we’re doing “right” today is likely going to be “wrong” tomorrow, as long as we make the conscious effort to improve every day.

The person we’re interacting with today may be in the part of their journey that’s similar to our own a year ago. What looks “wrong” now, may be right, all things considered; writing comments for every line of code may be right for someone just getting started.

I’ve been avoiding videos, articles, and other types of content that try to grab us with:

• “You‘re doing it WRONG!”
• “NEVER do this”
• “ALWAYS do that”
• “I have read all these books on –whatever-. Here is what YOU should ALWAYS do.”

I remember back as teenager when I learned how to play Black Sabbath’s Paranoid on the guitar. I played it for years thinking that was one of the easiest tunes ever. Until I find a video of Tony Iommi (the person who wrote the song!), talking about one tiny aspect that pretty much every guitar player gets wrong when playing that song: “they play the main riff off the 7th fret on the 5th string, instead of the 12th fret on the 6th string, where it sounds heavier…”

Growing up in Brazil, it took me years after I’ve moved to the US to finally hear I was pronouncing words such as pitch and peach exactly the same way (yup, the attentive reader can probably see how I could sound rude at times).

Far too often we won’t do something because of the fear of being wrong.

We don’t try a new language because we’re afraid of mispronouncing words.

We don’t try playing an instrument because we’re afraid it’ll sound bad.

I’ve heard Tim Ferriss suggest we ask 3 questions before offering an opinion. Now that is good advice. I also like Derek Sivers’s thoughts on “your first reaction is usually outdated“.

Hello there, future-me; do you think I’m doing it wrong right now? Be thankful that I am doing it; if I weren’t, that version of you would not exist.

“Always remember that to argue, and win, is to break down the reality of the person you are arguing against. It is painful to lose your reality, so be kind, even if you are right.” – Haruki Murakami

Let’s be kinder to ourselves and others.

🚨 Spoiler alert: the evidences you seek aren’t likely to be found here!

There are a number of studies available on the web with numbers, charts, etc. This post does NOT include any of that.

For the readers who enjoy geeking out on studies and researches, here are some great books that include some of that:

• Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations

• Specification by Example: How Successful Teams Deliver the Right Software

What follows are some of my current thoughts on the topic at hand.

Weeks ago I shared some thoughts on this question I’ve heard many times over the years: Is TDD something you do sometimes or all the time? It generated a great conversation with an old fox who has been stalking me for several years. 😉

It started like this:

I’ve never seen good evidence that TDD is better. Oh sure, there are opinions, but not concrete evidence.

That’s a common comment, so I wanted to explore it more.

As a guitar player, I’m often asked questions like “who do you think is better: Tony Iommy or James Hetfield? Yngwie J. Malmsteen or Eddie Van Halen?”

At one point in my life, I’d answer Iommy. At a later point, Hetfield. Then, at another point, Malmsteen. And depending on the day, Van Halen.

It’s all contextual. I’ve listened to a lot of music by those four guys since the mid 80’s. The circumstance, the people who were with me, my personal experiences, all of that influenced who I thought was better at one time or another.

But better at what?!

Record sales?
Influence over new bands and/or guitarists?
Number of hit songs?
Number of memorable riffs and/or guitar solos?
Career longevity?
Guitar playing technique? Innovation?
Caring for their fans?

As the old fox said, “oh sure, there are opinions…”

Over the years, I couldn’t agree with my own opinion, let alone the opinion of others. So who is better?

The fox says “…but not concrete evidence.”

Wait; what kind of evidence are we looking for? I think we’d only know that if we could answer the “better at what?” question. In the case of guitarists, if we’re considering “better at selling records”, that’s something measurable.

But who’s better: a best selling or the most influential guitarist? The latter? But most influential at what?

At some point, I gave up on answering those questions. I’ve let it go. Depending on a number of factors based on a single moment of time, I will deliberately choose one guitarist over the other.

But I digress…

So, is TDD is better?

Better at what? Better than what?

Better at decreasing bugs?
Better at increasing code quality?
Better at bringing clarity to our thoughts before we decide how we want to implement something?

Or…

Better than not practice TDD?
(I can’t come up with any other options here…)

If we manage to add more context to the question, then we can look at the next one, “is there any evidence?”, and define what kind of evidence we’re looking for, and finally look at how we could possibly measure it.

Say the question is, “is TDD better at delivering software faster than not practicing TDD?“

If we’re looking at it only in the context of a very short period, we may find it that it is not.

If we’re looking at a longer period of time, I’d bet it is better.

But we should figure out what we’re measuring besides the time spent writing tests. For example:

• time spent reading code until we feel confident to change it
• time spent on a debugger troubleshooting issues

The old fox is wise; one needs to try something before reaching any conclusions:

“I’ve tried it. I can’t say I saw an improvement in the code or fewer bugs. There’s no way to accurately measure that.”

How do we see improvement in code?

There are code metrics we can use, such as cyclomatic complexity (CC), but can one see improvement in code if CC decreases? If developers working on the code can’t yet appreciate low CC, they don’t see it as an improvement.

Occasional music listeners may not appreciate improvements in remastered albums. Many times we need to be trained so we can start seeing (perceiving?) things as improvements. As someone who dabbles at playing classical guitar, Julian Bream’s Masterclass videos has made me hear and see nuances I was respectively deaf and blind to before.

The fox continues:

“But when I wrote code I refactored a lot, not just the code I was writing, but the existing code around it. So that could have an effect on quality.“

That reminded me of Michael Feathers’ Working Effectively with Legacy Code, when he talks about pinch points (here’s a good short description).

But the old fox wasn’t finished:

“I think there are enough developers out there that don’t know how to do unit testing properly. If we want to turn them into TDD devs, first they need to learn how to write good unit tests. Here’s an example: At my last job, I was moved to a team that had little unit testing. They owned code that I was told “It can’t be unit tested.” I showed them it could. Once they’ve learned how to effectively unit test, only then should they be pushed to TDD. At least, that’s my opinion.“

BINGO! That resonates a ton with my own experience. Years ago I even gave a talk titled “I Cannot Write Tests for That!”: UI Edition. I’ve had several similar experiences coaching developers into the practice just like the fox described. I draw great satisfaction from helping developers through that journey, and more often than not, I don’t have to “push them to TDD”; they are the ones “pulling for it”!

Final thoughts for now…

If I am to look for “evidences that TDD is better”, I think of what works for me and those around me:

• The time spent designing potential solutions to problems is time well spent
  • and it is shorter than the back and forth of implementing features without designing them
• It’s very satisfying to be able to refactor implementation when there are good specs to back it up
• The level of willingness a development team shows to embrace changes
• It feels very pleasant and productive to collaborate with others and have conversations using well-crafted specs

Now if you excuse me, I have some TDDing to do.

The first “personal information manager” I’ve used was Lotus Organizer in the mid 90s. Then there was Microsoft Schedule+, later replaced by Microsoft Outlook, which I stopped using as my personal tool in 2010 or so.

I had a Palm OS around 2000 which I used mostly for note taking. Then a Microsoft Pocket PC in 2003, I think, which I hoped it’d integrate with Microsoft OneNote, which I used for some time.

Then I got into Onfolio (which allowed downloading webpages, organizing them into collections, and building my own knowledge store). A nice little tool that vanished without further notice shortly after getting acquired.

Other than OneNote, all of those things disappeared in a matter of just a few years.

ALL of them. In just a FEW years.

How can we trust technology when it goes out like that? But I digress…

In 2009, I heard of Evernote, when they were still in Beta. I gave it a try and have been using it since then. Being able to use the same tool seamlessly on a PC, Mac, iPhone, iPad: that’s what got me hooked immediately. I’ve put out many blog posts on how I’ve been using it.

I always keep an eye out for different ways to improve my process and systems. Up until 2020, I haven’t found any reason to replace Evernote with anything else. Compared to the options above, this tool has had a very long and stable run for me. Kudos to them.

Their first version was implemented in WPF, which they’ve learned wasn’t the best choice for their product, and so they rewrote the entire software from scratch after a while. As a consumer of their tool, I remember switching between the two versions going painlessly. As far as I remember, they reached feature parity quickly (at least for the features I used extensively at the time).

But then in 2020 comes another full rewrite: as I understand, they had a different codebase for each operating system they supported (PC, OS, iOS, Android…), which was very hard to keep up with (adding features, fixing bugs…). So this time they went with ElectronJS.

I got into the beta program to try out the new version. I use the tool all day long, on a PC, on a Mac, and on my iPhone. Within a month I had to go back to the previous version, not because of the expected stability issues of a beta version, but because of the large number of missing features I’ve been relying on for several years.

To mention a few of those features:

• Lack of support for tabs. Here’s one of my use cases for it.
• Lack of multi-window support (I can open notes in separate windows, but I can’t have multiple Evernote windows)

As someone who works with 3 computer screens most of the day, being able to use those screens effectively is a must, and a tool that doesn’t let me run multiple windows severely impacts that need.

Evernote “Legacy”: multiple windows and tabs

I’ve reported to them all of the use cases and reasons why I was falling back to their “legacy” version, at least on my Mac, which is where I use the tool the most. I’ve kept using the latest version on my PC so I could stay updated on their progress. As I saw their comments about which features we could be expecting soon, and the lack of information on most of the features I was interested in, I figured I should start looking for alternatives.

With so many people swearing by Notion, I looked into it. Didn’t like it.

At a Virtual Brown Bag earlier this year, I heard of Obsidian. It looked interesting, so I noted I should look into it. A few months later, I start hearing good things about it from people whose opinion I trust. So I decided to spend more time on it. I’m liking it.

I’m gradually learning more about the tool. It doesn’t seem to fit all of my use cases yet. But it does work really well for some of them.

For some things, I’ve either completely moved over or started to move parts of it. For example, keeping track of my book reading or how to decide what book to read next, and building and maintaining my book library. Also, keeping track of quotes that inspire me.

I’m not in a hurry. I’m not desparate to use the flashy new toy. And I do see me using the different tools for different parts of my system.

Obsidian has one of the same issues that the Electron-based version of Evernote does: lack of multi-screen support. The latest version added an option to open/move a note into a separate window, but it currently doesn’t work well on the PC and Mac. It seems fine when the windows are showing on the same screen, but it gets really funky when I move the new windows to another screen.

Obsidian: Multiple windows and panes on a single screen

Looking at where Evernote has been putting their effort for the last 2 years and the direction they’re going, and where Obsidian is going with their community plugins and all, I’ll keep working at my gradual transition between the two tools.

I’ll put out separate posts talking about specific use cases.

“Slow progress? So what, time will pass one way or another.” I don’t remember where I’ve read that quote, but I always think of it. Much like this one, which I’ve read on The Artist’s Way:

Student: “But do you know how old I will be by the time I learn to really play the piano/act/paint/write a decent play?”
Teacher: “Yes… the same age you will be if you don’t.”

Not far from what I’ve shared about the Search for Perfection.

When I release my latest song, an old friend told me this: “I see your videos and think they’re really cool, and I feel envious because I can’t get my stuff together like you do.”

That comment inspired this post, which contains some of the things I’ve shared with him…

The main riffs for that song were written 10 years ago. I wrote the main ideas for the lyrics 5 years ago, and I finished the main structure of the song around the same time. I started recording the song in April this year. I’ve only finished lyrics, vocals, guitar solos around September/October, and the song was finally released in November.

Ten years.

I have many other songs that have been in-progress for years now: 5 years for two of them, 13 years for another, and there’s one sitting in the backburner that goes back to 1995.

Do all of my songs take that long from initial conception to release? No. Sometimes it takes me as little as 2 to 3 months. No specific reason; I may just feel like I have all of the parts and so it happens I have the time to get it all done quickly.

However little time I have, I record song ideas on my phone and store it away in a backlog. I write ideas for lyrics and put it away. Every once in a while, I listen back to those ideas, and if I feel an urge to work on any one of them, I make the time and make some progress. Sometimes I may be able to wrap it all up within a month, other times it may take me years. No biggie.

For me, it’s important to get it started, get the ball rolling. When it’s done, it’s done. Time has passed. Progress has been made. Results have been achieved.