Note: The code snippets below are just examples, and have not been tested.

I recently attended the Laracon 2019, which was a first for me. It's a digital conference, in that nobody attends a venue or location - attendees can just join a private Zoom video chat instead.

One of the talks was "Writing less complex, more readable code", by Jason McCreary. Where he talks about writing cleaner code bases, and removing all the over engineering that is oh so common nowadays.

He touches on the use of comments, and how to use them effectively - what they represent, and more importantly - how necessary are they? So here's what I think of Comments, and then I'll move onto Pseudo Code (you'll understand why Pseudo Code is important by the end of this)

Comment all of the things!

Comments. What? and Why?

Comments are used in code to add notes to an implementation to assist with the understanding of the code. In education, and often in code reviews, comments are encouraged. They give a piece of code a "skeleton", then the code within gives it a "body". Comments are not executed, and generally not read by the compiler.

Sounds great right? Well, not always. Consider the following code;

Doesn't really do much, but it's already 57 lines long, and a lot of that is comments. Let's look through the comments, and see what is necessary, and what isn't really adding anything to the reader.

We can see from the method declaration public function empty():selfthat the function is going to empty something, and the method is fluent.

First comment - Empty the items. Ok, let's get rid of that. We know what it's doing, the method is called "empty". Further, let's remove L8, as we know from declaration that the method is fluent.

Doing this to all the methods, reduces our class from 57 lines, to the following;

57 lines down to 48 doesn't seem a lot. But in real terms, that's nearly 20% reduction in terms of "readable code". We can still see what the class is doing, and what each method is responsible for - as the names and syntax give that away for us. So, if we shouldn't need comments for things like structure, when do we ever need them?!

Appropriate Use

I will always advocate the use of comments, when necessary. They are a great tool for yourself, and any person who inherits your code base. For example, I was recently reminded of a comment I left on a code base a while back.

https://www.linkedin.com/feed/update/urn:li:activity:6509348215635140608/

As you can see from that example, comments should be used to communicate with other developers. I often use comments to do "brain dumps" on the screen, and I'll log what my thought processes are whilst programming the given functionality or implementation.

The best implementation of comments that I see are conversational.

Both of the above, are information that will not be exposed through syntax, however might prove useful to any developer looking over the code.

But what about pseudo code? How does that even come into comments?

Comment Evolution & Pseudo

You're on a new project. You have to connect to an API, fetch some data, and store it. Pretty standard stuff, you open your IDE, go to the project, and get started.

Most functions, from what I've experienced, and seen within the industry, begin with Pseudo Code. Plain English code, that you can then use to explain the code to someone. From this, you build out your requirements. For this project, you'd probably have something like this to get started;

This is all great - as you can see what's going on, and in what order. Over time though, you begin to "flesh out" the functionality, moving you more to the following;

Looks like a basic working concept for the request. We now need to review it, and make sure we're happy.

The comments, aren't really giving much assistance at this point, so let's remove some.

Our code makes sense, we can infer logic from the names of variables and the Classes being used.

The comments in this case are adding to the code, and give supporting information.

We've gone from a comment-driven pseudo code implementation, to now a working concept with comments that have value.

Adding comments, for the sake of adding comments is a very time intensive practise, and can even lead to issues such as Spaghetti Code. There's also the concern over "Visual Debt" that should probably be addressed - however that's for another day!