Code comments should help you and other developers understand the code. Or “why project code standards can result in unwanted behaviors”

The purpose of commenting your code is to help you and other developers that come after you to understand the code. If a code comment doesn’t offer anything in addition to the code itself then it’s pointless and just adds noise.

Method and variable naming is also important, a descriptive method name shouldn’t need copious additional inline comments if it already describes what it does. Obviously you don’t want the extreme and have a method name that’s hundreds of characters long. Be sensible.

I often come back to these 2 Twitter posts that illustrate how inline comments that state the obvious are useless:

Another one making the same point:

There’s many reasons why developer’s comments add little value. The main reason is probably just not putting in the effort and time to write something that’s useful. There’s another reason though that leads to documentation that looks exactly like this:

 * This method retrieves an Account.
 * @param accountId the account id
 * @return the Account
public Account retrieveAccountById(String accountId){
    // code here

First, the name of the method, the parameter and the return type tell you a lot about the purpose of this method. So why would anyone take the time to write “This method retrieves an Account” that clearly just repeats what the code already says?

Have you ever seen statements like these:

  • Every Class must have JavaDoc that describes the Class
  • Every method must have JavaDoc that describes the method and it’s parameters

This is an example where standards encourage unexpected or unwanted behaviors. The intent of both of these statements is good. In most cases it is beneficial to have documentation that helps others understand what the code is and what is does. There is a point however that if you’ve named your method, it’s parameters and it’s return clear enough, there isn’t anything left to say in the documentation for the method.

“But the code standards say we must write JavaDocs, so I have to write something!”

Standards and rules are established for a purpose, but they have to add value. Be flexible. If something doesn’t add value, you shouldn’t follow it blindly. Do what makes sense.

Building variations of the same app to practice or learn different tech / frameworks / libraries

Once you’re familiar with building a solution for a given problem, as you’re learning new languages, frameworks, libraries or whatever is your current focus, there’s no reason why you have to build something completely new when you’re learning something new. Learning to solve problems is valuable and essential, but if your current goal is to build some experience with a new framework for example, there’s no reason why you shouldn’t rebuild something you’re already familiar with.

For example, if you’ve come across any of my posts before, you’ll know I’ve been spending a huge amount of time writing code around solving and generating Sudoku puzzles. While this has been an interesting exercise in itself, the real goal was to use it as set of related problems for practicing building apps with React and AWS Lambdas.

Even for the frontend I’ve gone through a couple of variations:

The initial frontend app was React with Redux, and it’s served from a public S3 bucket here: . The source for this app is here:

I then redeployed it using a CloudFront distribution, with a Route53 record using my domain name, that’s here (it’s still the same app at this point) :

Recently I rebuilt it using Redux instead of Flux. I don’t have that deployed anywhere yet, but the source for that app is here:

I was planning on updating the app to download pre-generated puzzles. That part took me off on a wild goose chase, on working out how to generate puzzles and grade them with a human solver to assess their difficulty. Now I’ve got that part working, I can come back to the frontend app again.

This app, the frontend and the backed solver, generator and grader has kept me busy for month. You don’t have to build something new everytime, if you’re struggling for ideas for personal projects, it’s ok to rebuild something you’re already familiar with.

What is the ‘main thing’ in software development?

Software development is about solving problems. It’s about solving problems in an effective way that adds value. It isn’t about programming languages and writing code. Programming languages are tools. We use tools like Cloud compute to run our solutions, and we build solutions with tools like programming languages and frameworks.

It’s all about solving problems.

If you’re getting started in software development as a career and are putting all your effort into learning a programming language, remember that’s just a tool. It’s how you use it to solve problems which is the important part.

The single most valuable advice I can offer to new software developers

When starting out in software development or even learning a new language as an experienced developer, the most likely cause of most ‘I don’t know why this code isn’t working’ type questions is pretty simple:

What you think your code should be doing is often not what it’s actually doing.

This seems like an obvious observation, but it’s easy for even an experienced developer to get caught up in what they think their code is doing, and they forget to look at what it’s actually doing.

Next question: “ok, so how do I find out what my code is actually doing at runtime?”

Answer: you use a debugger. You step through your code and you compare what you think each line should be doing with what it’s actually doing. At some point you’ll find a line where you assumed the code was doing one thing but it’s actually doing something else. It could be the variable of a value that you were assuming to be a particular value but actually it’s something different and it results in a result that’s different from what you were expecting. It could be a condition you were assuming to be true is actually false. It could be a block you were assuming would always get executed but never is. There’s many reasons.

Learn how to use your debugger:

  • Practice stepping through your code
  • Learn how to set breakpoints
  • Learn how to set conditional breakpoints (break when a certain value or condition is met)
  • Learn how to inspect value of your variables
  • Learn how to change values at runtime – what happens when this value is 1 instead of 2?
  • Learn to break on an error
  • Learn how to step backwards to a previous statement (not all debuggers do this but it’s a useful feature)
  • Learn how to change code while you’re debugging

Knowing how to use a debugger is an incredibly valuable skill. It’s seems a given that as a developer you would learn to use and use a debugger as an integral part of your development, but all too often though when asked ‘why is this code not working’, if you ask ‘have you stepped through in a debugger to see why it’s not working?’ the answer is ‘no’.

Learn to use your debugger!