Software Development: On A Need to Know Basis

A good clear principle for any software engineer and developer is that any class, method or function that you create and use should only have the bare minimum number of necessary arguments passed into it to correctly operate and not know more about the system than it should. Recently I have been doing some merge reviews and too many times I have seen the below case from both junior and (surprisingly) senior engineers:

...
Object object = getObject();
Date objectDate = getObjectDate(object);
...
private Date getObjectDate(Object object) {
    ObjectReader objectReader = new ObjectReader(object.getId());
    return objectReader.getDate();
}
...

As soon as I see the above I leave a comment on the merge request, something along the lines of “Why does the getObjectDate(Object) method need to take the entire object instance?“. This then forces the one who submitted the merge request to stop and think what is being done, and should it be refactored in someway.

In this case, the method only uses the object’s id to build a reader and get the date from the object. The actual object is not being used at all. Instead of passing the entire object into the method the id should only be passed in. There is less overhead. We should be seeing something like below:

...
Object object = getObject();
Date objectDate = getObjectDate(object.getId());
...
private Date getObjectDate(String objectId) {
    ObjectReader objectReader = new ObjectReader(objectId);
    return objectReader.getDate();
}
...

By only passing the bare minimum to the methods or classes then you are ensuring that your system does not know more than it needs to. By enforcing this rule, IMO you are ensuring that the system is:

  1. Cleaner – you know exactly what is being used and for what purpose.
  2. Safer – you are ensuring that only what you want to be manipulated can be manipulated and where.
  3. Modular – there are clearer separations between what needs to be done with what and where.

So when you are creating new classes or methods then consider what you are using as your arguments, what the method needs to do, and what exactly you need to pass in. Taking the time to logically structure your code and think through what is necessary for the method to do its job will save you massive headaches in the future. Short term pain, for long term gain 🙂

Moving to Visual Studio Code

I performed a clean install of Windows 10 on my Surface Book 2 recently and I have not installed my default go to Java IDE, which is IntelliJ. Instead I have now moved to using another tool, which I am finding is much more versatile and beneficial; Visual Studio Code. I have previously used Visual Studio Code but mainly as a way to edit my various data files such as XML, XAML, JSON, etc. and not any of my source code files like Java, C# or C++. I treated VS Code as a text editor only previously.

Visual Studio Code comes with a crazy amount of extensions which is great because that gives you options. To get started with Java, the extensions that I suggest you get is:

  • Java Extension Pack – this comes with all the necessary Java dependencies for Visual Studio Code such as proper language support for Java, Debugger for Java, Java Test Runner, Maven for Java.

On top of that extension you will need a JDK installed. If you want to know how to setup the environment for Java then have a look at the comprehensive page that Microsoft has created here. Microsoft also has a pretty sweet tutorial about how to build a Spring Boot application that can be found here.

One thing that IntelliJ made super simple was the compilation of Java code and managing all the dependencies, not to mention providing some really convenient debugging tools and project management. This makes it a really powerful development tool. When I was at university I primarily used a terminal or command console with a basic text editor for developing software, but as I moved towards writing commercial software for the company I work for I relied less and less on the terminal and command console and more on the IDE for the heavy lifting. Now that I use VS Code I am using the terminal and command console more again, and all of the necessary information such as the class path, dependencies, etc to ensure everything complies correctly is critical. Looking at this now, I really appreciate what the IDE does to simplify development process but realise how important it is to know the fundamentals.

I wrote about a similar scenario a month or so ago regarding Git (this can be found here) and how important it is to actually be really familiar with the Git commands through a terminal and/or command console because it is cross platform but it allows you to truly understand what is going on. Using a GUI is fine but all that does is issue the same commands you would use if you were using a terminal or command console. Using VS Code and the terminal to compile and execute my Java applications has allowed me to really appreciate what the IDE does to simplify the development process but also familiarise myself with the fundamentals and important concepts that can be carried between platforms.

 

Software Development: Writing Better Code Through Code Reviews

One of my favourite parts about being a software engineer is reviewing code. You get to learn alot about an individual from the code that they write and also learn how to potentially do something more efficient or understand a component of the application you had little exposure to before. If I look at a merge request, within the first few lines of code that is submitted I can get a good sense of how many years they have been programming and if they know what they are doing or if they just copied and pasted something from StackOverflow.

Graduate software engineers, entry level software engineers, or individuals who have just started programming, will often leave out some crucial elements such as appropriate null checks, logging, comments or appropriately named classes, methods and variables. There is nothing worse IMO then looking at some code and seeing a variable named “numbers”. It is most likely some collection object like a List and contains numerical values but offers little context in respect of the application it is used in. It may make sense to the person who wrote it but it probably won’t to others and you will most likely forget its context several months down the line. Red flags are very easy to spot here.

The more experience you get, the quality of the code that is submitted is generally far easier to read, is structured and broken down logically, has been optimised, there are the appropriate exceptions and null checks in place and the classes, methods and variables are named appropriately. But to get to this level you not only need to write a good amount of code but also look over and see how others are structuring and writing their code and do reading/research in your own time.

At work when I get a request to do a code review there are a number of elements I look at. Some of which include:

  1. Appropriate and meaningful class, method, and variable names.
  2. Small, compact and single purpose methods.
  3. Appropriate null and boundary conditional checks.
  4. Some level of optimisation on the operations performed.
  5. Meaningful unit and/or integration tests have been implemented.

At times I think that I am fairly harsh on the individual who submitted the code to be reviewed but then I think to myself that the better the code repository is in, the easier it will be to maintain and if good code practices are enforced then it will make everyone a better programmer. If I didn’t start being critical of my code and trying to better myself then when I do the code reviews I probably wouldn’t be as critical of theirs. Setting a high standard will only make the lives of software engineers working on the project much easier in the long run even if there is short term pain.

Git. Command Line or Graphical User Interface?

I was doing some reading today about Git and whether software engineers (or anyone else for that matter) should learn to do all their changes, etc for Git using command line or a graphical user interface. It was an interesting piece and some valid points were made for both using a command line and/or a graphical user interface. Me personally, I use a graphical user interface because it is extremely easy, hooks directly to the Git commands (under the hood) and can give you a nice visual tree of what the repository looks like. For your information Sourcetree is the client I use. However the more programming and development I do, the more I appreciate and want to learn what, how and why.

Some of the reasons why using the command line approach is valid and well worth it include but not limited to:

  1. Platform Independence:
    • No matter what operating system you are on, the commands are universal. So if you can use the Git commands in a Linux environment, then you will have absolutely no problem whatsoever doing it on a Windows or MacOS machine.
    • Git clients like Sourcetree for example are not available on every platform, and I imagine the other Git clients are also not available on every platform.
  2. Understanding:
    • This fundamentally for me is important and I think should be high on everybody’s list when using something.
    • By using the command line you get a level of understanding of what exactly you are doing, whereas using a graphical user interface this level of understanding (well to me) is abstracted and partially lost.
    • It also comes back down to point 1. If you understand what you are doing then you can take it to any platform.

Now using a graphical user interface is not the end of the world. Sometimes you just want to get something done and using a terminal if you are not comfortable with it can be extremely daunting. I personally would never be caught dead (well right now anyway) resolving merge conflicts and looking at diffs using a command line, and rebasing using a graphical user interface is so much easier.

I did some quick Googling and found what I feel are two really good resources that help and ease you into using the command line for Git. There is Try Git and Learn Git Branching. There are probably more out there but those are the two that I felt provide a good starting point. If there are others out there that you use or feel that there is a resource that is definitely worth reading then please add a comment below (sharing is caring) 🙂

Kaspersky Anti-Virus + Microsoft Windows 10 + Microsoft Office 365 Issue

Recently I had updated three of my household’s Windows 10 machines (one Surface Book 2, one custom built gaming PC, and one ASUS laptop) to the latest stable/release version of Windows (Microsoft Windows April 2018 Update). Each of machines also have a copy of Microsoft Office 365 installed, along with the latest version of Kaspersky Anti-Virus.

What I have found after the Windows 10 April 2018 Update installation; Microsoft Office 365 fails to properly recognise that I have a registered version. I can still use the products in the suite such as Word, Excel and Outlook, but am given 3 days to rectify the problem before the product runs in a limited capacity. I have the correct account logged in, the credentials are correct, and if I try to register and authenticate via the Internet option (phone option is not available) it completely fails. Googling or Binging the error code that is produced does not show any resolution or worthwhile results.

Restarting the machine, restarting any of the Microsoft Office 365 products also does not seem to resolve the problem. Initially I thought that communication to the Microsoft servers was unavailable (sometimes servers go down), but trying to use the product at any time resulted in the register/authenticate prompt to appear on all the machines. So out of sheer desperation and curiosity I thought perhaps I should disable my anti-virus because sometimes they can cause problems with certain applications. Low and behold when I booted up any of the Microsoft Office 365 products the registration/authentication prompt no longer appeared. It appeared that Kaspersky Anti-Virus was blocking or limiting my ability to properly communicate with the Microsoft servers.

Now that Microsoft Office 365 could be restarted without the register/authenticate prompt appearing I decided to re-enable my Kaspersky Anti-Virus, restart my machine and launch the Microsoft Office 365 products. Still no more register/authenticate prompts; great news. Whatever happened between the Windows 10 April 2018 Update, Kaspersky Anti-Virus and Microsoft Office 365; it seemed like it invalidated my copy of Microsoft Office 365. If you encounter the same problem after updating your Windows 10 machine then try the following steps because they worked for me:

  1. Close any open Microsoft Office 365 product you have open.
  2. Disable any anti-virus that you have running (if possible).
  3. Open a Microsoft Office 365 product.
  4. Close the Microsoft Office 365 product.
  5. Turn on your anti-virus.
  6. Restart your Windows 10 machine (this is optional).
  7. Open a Microsoft Office 365 product (the register/authenticate pop up should no longer appear).

Hopefully the above steps helps to resolve your problem.

Being an Xbox and Windows Insider

After installing a new Xbox OS update on my Xbox One X console, I launched the Xbox Insider application to see what the changes were and if there was any new Quests, Polls, Survey, etc. I noticed that I had been an Xbox Insider for 3 years and 11 months, essentially as soon as there was an option to try the latest features and opt in to new functionality I jumped on it. Along with being an Xbox Insider, I am also a Windows Insider; but I have not been as active in that program in recent months. Checking out the new features and functionality that the teams over at Redmond and around the world working at Microsoft are developing is something that really excites me. I love trying out new gadgets, devices, software, etc. What Microsoft is doing with both their Windows and Xbox platforms, allowing individuals to try new features and provide constructive criticism and feedback is extremely positive and very pro-consumer. It helps ensure that the best product is produced.

However by trying out early builds on either platform is not always fine and dandy. There have been a number of times when simple and basic functionality such as Xbox Live Party Chat did not work at all or installing and/or updating applications completely failed. Luckily to combat this, Microsoft has separated the Insider builds into “Rings” which determine the stability of each build and how new the features you will be getting are. If you are in the Alpha Ring (like I am) then you will get the latest and potentially breaking builds or you could be in the Delta Ring and get a significantly more stable build but not have the newest features. This creates choice for the individual while still allowing them to contribute to the evolution of the platform and assist in bug reporting (something as a software engineer is extremely helpful, the more testers the better). More software companies really need to start providing this feedback process as software is becoming ever increasingly more complex.

Many people will most likely not want to be involved in trying unstable or incomplete builds/features for various reasons. To me though, providing feedback and helping the features become less buggy and complete ready for the masses is rewarding (even though I do not write a single piece of code). To make trying out the new features more enticing and understandable, Microsoft has created Quests and Surveys. Generally if there is new functionality added after an update a new Quest will appear which shows you how to activate and or try it out. It is a very handy way to get your device configured with the new features. The Surveys provide an easy way to communicate how you find the new features (if they even do work as intended) and if there are any issues that you encountered. Reporting bugs and issues is also extremely easy. Each platform as their own Hub that allows you to provide as much detail as possible to help Microsoft resolve your problem, and if others have the same issue then they can piggy back off yours and add further information and diagnostic data.

Overall the entire Insider experience on both platforms has been fun and for someone who is looking to try new features before others, or just wants to help Microsoft out in providing the best possible experience for everyone then the Insider programs are a must. For more information about the Xbox Insiders Program check out the following link. For more information about the Windows Insiders Program check out the following link.