loading...
Cover image for The 10 Commandments of Programming

The 10 Commandments of Programming

prjseal profile image Paul Seal Originally published at codeshare.co.uk ・5 min read

1. Thou shalt name things properly

As you probably know, naming things is hard, but it isn't impossible and as long as the name of the class, method, object or variable etc makes sense and helps the reader to understand what is going on, then you are doing it right. 

Please don't be the person who does this:

var button1 = new Button();

var textBox3 = new TextBox();

Whilst the code itself may not be realistic, the point here is the lazy naming. It is not helpful to name somthing button1 or textBox3, give it a meaningful name.

2. Thou shalt not write obvious comments in the code

I personally think you shouldn't be writing comments in your code. I think you should write the code in a way which explains what it is doing itself without the need for comments. With that in mind, this commandment refers to those comments like this:

//get the user from the database
var user = GetUserFromDatabase();

//send an email to the user
var success = SendEmailToUser(user);

Those comments are just pointless. It is obvious what the code is doing there. If you really must write comments, use them to explain why you are doing something instead of saying what you are doing.

3. Thou shalt not commit secrets to open source code repositories

We all love open source software, and some of us even like to contribute to them or create our own repositories. We are good people, but don't be fooled, not everyone has good intentions, and some nasty people create bots to carry out their evil work.

You should never commit any keys or secrets to an open source repository because there are people who go through the commit history of public repositories looking for such things and using them for no good.

Use things like 'AppSettingsSecrets.config' locally that doesn't get checked into source control. You can use environment variables and key vaults too.

4. Thou shalt not duplicate code more than once

This might sound like a contradiction, but think about what it is saying. It says you can be forgiven for duplicating some code once in the same project, but if you need to duplicate it again for another part of the project then maybe you need to refactor the code so it can exist once and be called from all of the different places which need it.

5. Thou shalt not store passwords in the clear, or with a weak hash algorithm

This one is unforgivable. No one should be storing passwords as plain text in a database, or using weak hashing algorithms such as MD5. 

If your data is breached, which is happening more and more it seems these days, you want to make it as difficult as possible for hackers. Ok so they managed to get hold of your data, but if you'd done things right, they wouldn't be able to access password and other personal data because you a very strong encryption method like AES 256 with a different salt and vector per record.

6. Thou shalt not steal other people's code

You need to be careful when using someone else's code. If you copy and paste it into your program, you need to be sure that you aren't violating any licences. You might think that you can just rename the namespace, classes and method names, but if the code still looks like the original, you can still be sued. There is a famous court case where Oracle who owns Java sued Google for copying its APIs.

There are so many different licences out there to understand, just because something is free, it doesn't mean you can do what you want with it. The GPL licence attempts to force people to release their source code which might be a problem if you are working on proprietary software. 

This article will help you understand more about software licences.

7. Thou shalt not take on unnecessary dependencies

If you are a web developer, you have probably used jQuery at some point. Do you really need to use jQuery any more? How much of it are you actually using? If it is just to get elements by their class name or id, you can do all of that with vanilla javascript. Have a look at this website which tells you why you might not need jquery.

What about dates, do you really need to load in momentjs if you just want to format a date and time. 

Surely the best thing to do, is find out the few lines of code you need in your project to achieve these things and eliminate these dependencies, unless you are using them heavily.

8. Thou shalt not write tightly coupled code

Tightly coupled code is code that can't be tested easily. It is code which depends on other code to be able to run. It reduces flexibility and re-usability of code.

Test Driven Development is a way of writing your tests first, then writing your code. You only write enough code to pass the tests. You write enough tests to make sure the code fulfills the requirements. If you are writing tightly coupled code it makes it harder to test. Following a TDD approach gets you thinking about how to write your code in such a way that it is not tightly coupled to any other code. You should use interfaces for your services and dependency injection to inject these services in to where you need to use them.

9. Thou shalt not swallow errors

Let's face it, we have all probably written a try catch statement where the catch just swallows the error so the application doesn't throw an error. This is bad, really bad.

You should at least be logging the error before swallowing it.

In an ideal world you will catch the error, log it, react to it with your code and throw it up to the next level where you can handle it appropriately there too.

10. Thou shalt not use hardcoded values

Please don't use hard coded values in your code. Come on, how annoying is that. If the value needs to change, what are you going to do, find and replace all occurances of "2"? 

It is much better to use constants, variables or enums instead, where they have a meaningful name of what that value represents and you only have to update it in one place?

Want to have your say?

If you disagree or want to add any commandments, please either comment where you saw this post or tweet it with your comments and get the debate going.

Discussion

pic
Editor guide
Collapse
jorgecc profile image
Jorge Castro

If you are a web developer, you have probably used jQuery at some point. Do you really need to use jQuery any more?

https://i.imgflip.com/30qcq1.jpg

Let's me be over-defensive (or pre-emptive defensive) on the next point:

The use of JQuery versus Vanilla Javascript depends on taste. JQuery is mostly syntax sugar but it's a consistent syntax sugar (instead of Vanilla JavaScript).
However, my main concern with the comments against JQuery, they are usually accompanied with JQuery is dead, long life to JavaScript... JavaScript together and Angular, or Reactor Vue. So, we are tossing a single (one file) library because it's bloated and we are adopting instead +80 libraries that live on the node_module folder. So, if we want to criticize bloated libraries, then we should look at those libraries, and it comes accompanied by the point 7).

Collapse
dotnetcoreblog profile image
Jamie

I can't speak for Paul, but I think that the point he was leaving towards was to remove as many external dependencies as you feel comfortable with.

If you want to use jQuery, then got right ahead. But you might be able to achieve whatever you're doing without having to include it. And the same can be said for the hundreds of megabytes of npm packages that you're pulling in.

It's all about taste and comfort, if you'd prefer to use npm and/or jQuery then go right ahead. The way that I take point 7 is that you should think about what dependencies you're bringing on board when you bring them in, rather than just adding any and every package under the sun. The point being that you might be able to do it easier, with your own code.

Then again, like I say, it's all about taste and comfort levels.

On a personal level, I prefer to not use jQuery where possible because I remember a time when the most common answer for any JavaScript related question on Stack Overflow was "use jQuery". It's a useful library, to be sure. But I (personally) think that to many people use it as a crutch.

Again, just my two cents, and meant in a positive way in the hopes of fuelling discussion 😊

Collapse
thejoezack profile image
Joe Zack

I'm getting to where I really love having configs for most of my "constants". .NET makes it so easy to provide them via file, environment, or command line...why not! But uh, yeah...stop those hard-coded values from spreading before it's too late. Great read!

Collapse
dotnetcoreblog profile image
Jamie

appsettings.json is one of my favourite things in Core.

Collapse
greenroommate profile image
Haris Secic

--8. Avoiding tightly coupled and focusing on TDD adds extra layer of abstraction which then again adds complexity which leads to complications and unreadable code which was the thing that was being avoided in the first place.

Just because Uncle Bob said so doesn't mean it's good. Really check out the code written before by you or colleges. Did it actually help remove complexity or added shadowing and more spaghetti code. Controller->Interface->Service->Interface->Repository->Function1->Extra function->Function1->Function2->Function1... This is SOLID principle add interfaces all the way to abstract stuff and avoid repeating code which leads to numerous calls to other stuff and makes debugging harder. "Well we have tests" - no you don't you pass the tests which in the first place should not be isolated from the context and tested as unit/alone and proof to this is how much extra bugs do you discover after manually testing while all the other unit test are green? From my experience it's too much.

Instead of following some buzzwords like loosely coupled or TDD let's thing before writing code. If thing is bound to context and tightly coupled in real world it's supposed to be that way in the code or else it's going to get too abstracted and no new developers will be able to join project without spending month or even more to get understanding of the project. Don't interface everything and don't write too many layers or else we're going to continue creating patterns, architecture and philosophy about something that can be easily solved by thinking with your own head.

Now if you wonder why people are switching to FP I think this is the main reason too much "right ways" to do stuff which in the end appears not be so right. But I'm not sure about them to they also have too much complications lately: monad, monoid, haemorrhoids... Let's just write code: it's craftsmanship not engineering really.

Collapse
wparad profile image
Warren Parad

Our teams production secrets/credentials are never exposed outside of their production runtime memory (that includes never being written down anywhere). We never commit unencrypted secrets (open source or not). And when encrypted we of course commit them to open source, since we need them that way to deploy to package managers (for instance).

I suggest updating the commandment ~_.

Collapse
jwollner5 profile image
John 'BBQ' Wollner

I love this Paul - thanks for stating the obvious, since the obvious often isn't.

Collapse
andreasjakof profile image
Andreas Jakof

... 10. In compiled languages. Real „const“s are inlined as if you would have spread it directly in your code. So there is no reason not to do it.

Collapse
dannywalk profile image
Danny Walker

I'd add a bit to #8. Untestable code is instant legacy code!

Collapse
prjseal profile image