Coding Commandments: Stop commenting your code

 

This is a piece of ASP code. Yes, it still exists out there in the wild…

code-with-comment-top

I actually appreciate this comment. Not knowing ASP, this told me something valuable. The page is already showing when this section of the code fires.

Unfortunately, the comments don’t stop there:

code-with-comment-rest

Why are these lines commented out? Why were they there to begin with? Should I put them back? Can I use them for troubleshooting? Is the code broken because you replaced those lines with new lines? What is the meaning of life ?

So many questions. So few answers.

By all means – feel free to comment. When your comment adds value or knowledge to the person reading the code. And know that if you create a comment, you sign a life long contract to support and update that comment.

Comments can be powerful. They can be useful. In my experience, they are dangerous. Not because comments are inherently dangerous, but because those who wield them around with great force are typically not skilled enough to do so responsibly.

If you write clear, concise code that is properly structured, with many small functions, you will not need comments in your code. Your code will be ‘self-documenting’. And if you then find yourself in a position where you really have to make a comment in the code – feel free to do so.

 

 

 

 

 

 

 

 

 

 

Coding Commandment: Write Short Functions

Oh my oh my ! I just opened up a stored procedure. I thought it would be ok, after all, it was written by a senior developer in the company, who has proven his worth over and over again.

3 thousand 8 hundred and thirty 4 lines of code. I had to write this out – because it is so ridiculous.

I do not want to read this crap. It’s going to take forever to figure out what this does. I’m tempted to just start rewriting it straight away.

Short functions are important for a number of reasons.

  1. They are easier to write.
  2. They are easier to test. I’m not even talking about unit testing. Just good old eyeballing is easier also. And if you want to punish yourself, try to write unit tests for a 3000 line function. It’s a nightmare.
  3. They are easier to read. This is true not only because they are short – but they force you to give them proper names (or at least to try). So the code ends up reading like a story book.

Once you start to realize that your 3000 line ProcessData() function is a bad idea, breaking it up into smaller functions forces you to think about your code in a totally different manner. If ProcessData is a bad name, ProcessDataPart1, ProcessDataPart2 and ProcessDataPart3 are probably not a good idea either.

And if that’s not a good idea – it means that the functions need to become even smaller – because ProcessData2 does not perform any single action that I can name the function after.

Oops! I did it!

I tried not to say the words Single Responsibility Principle. I did. My bad.

There is an interesting side-effect to enforcing a minimum length on functions. It tends to lead to single responsibility functions.

There are very few things that I cannot achieve in 20 lines or less. Or, more specifically in a few functions where each function is 20 lines or less. Each function ends up doing a single thing well. It’s easy to test. It’s easy to read. And, when the roof caves in on me – it’s relatively easy to fix such a small function.

Oh, and it’s much easier for new developers to understand the code. Most of it is now written in English, not in C# anymore. When you finally find the C# code, it generally does something exceptionally simple. ( Keep in mind that lot’s of simple, little pieces can still create a massive, complex system.)

 

Be Pragmatic

Find your own niche with this stuff. 20 lines works for me. If memory serves, the Linux kernel team does not accept anything longer than 5 lines. I don’t work on the kernel.

A mentor used to say that if he could see the entire function on the screen at once – it was OK with him. I’m less trusting. You will always find that one developer who changes his font to a 6pt font – just to pass the code review, right?!

What is important is that you are consistent. Simply start breaking complex problems down into many more less complex pieces. You will see the benefits. I promise.

 

DevOps rule my world

By the way, a nice side effect of enforcing some sort of maximum length rule is that while it can be extremely hard to enforce the Single Responsibility Principle in code, it is really easy to enforce a max length rule in code. And since shorter functions ultimately leads to functions with fewer responsibilities, you are still heading in the right direction.

Don’t tell anyone that I said so….. but, you can even automate the check for function length and fail the automated build if it does not meet the expectation. But be nice and build in a bit of leniency ….

 

 

 

 

 

 

Coding Commandments

I want to write down a few rules that I tend to adhere to when attempting to build software.

I it very likely that none of these are original thoughts and I don’t claim ownership to any of these ideas. They are simply things that I have found useful and that might help someone else produce slightly better code.

 

How to make an Angular2 application run from the file-system.

I wanted to use Angular2 to write a very small Google Chrome plugin. It seemed perfect for the job, since Angular2 makes writing small web-components just so easy.

My first step was to see if I could run a very simple Angular app from the file system. If I couldn’t even get this to work – there really was no point in trying to build the plugin.

BOOM!! CRASH!! and 10 minutes of googling later – I found that numerous people were complaining about not being able to load their sites without some sort of web-server.

So, let’s make a long story short and show you how to achieve this:

  1. Open index.html
  2. Find the section
  3. You should see a line like this:
      
  4. Remove that line and replace it with a Script tag containing this text:
     document.write('');
  5. Almost done

Ok, any path in your (single-page) app is now being evaluated with the path resulting form that formula as the base.

So, you need to make sure that your code knows this. For example – I had to change my components to not use relative-paths like (“..\..\assets\bicycle.png”), but instead – simply reference “assets\bicycle.png” instead.

This approach makes your code work, both from a web-server and when you serve files from the file-system.

Ok, time to build that little Chrome application. I’ll post again when I have something to show.