Alessandro's blog

Thoughts on software development

Jul 20, 2016 - How to fold code regions with Netbeans

In C# language you can surround a block of code with #region / #endregion preprocessor directive.

#region lets you specify a block of code that you can expand or collapse when using the outlining feature of the Visual Studio Code Editor. In longer code files, it is convenient to be able to collapse or hide one or more regions so that you can focus on the part of the file that you are currently working on.

Java misses such functionality. While any IDE collapses methods or classes, there’s no unique way to collapse more methods together.
In Netbeans we can define a folding region using custom crafted comments in Java source code:

//<editor-fold desc="Add your description">
... your Java code here
//<editor-fold>

The result is pretty much the same as Visual Studio.

Unfolded code: Unfolded code

Folded code: Folded Java code! Well done, Netbeans!

This way we can group togeter related methods, collapse getters/setters, collapse loops inside big methods and in general manage code readability.

However, a folding region defined as above is displayed as a comment in Eclipse…

There’s a shortcut to insert a code fold in the editor: just type fcom and press TAB key.

Apr 27, 2016 - 3 flows antipattern

While maintaining an old Java enterprise application I got lost in the classical spaghetti code you would expect. After some days of staring at weird walls of code, huge classes and methods with at least one side-effect, I finally understood the logical flow of the program.

It isn’t easy to explain what each method does and how it achieves the result. This confusion arises from the fact that many classes violate the single responsibility principle in the same way: by having exactly three responsibilities. I call each one of these responsibilities “code flow”.
The first code flow is the regular one, when the application functions as expected. The second code flow is the error handling flow: whan something goes wrong take the else branch. The third code flow is the test flow, when some flag is enabled return predefined data or do not call external services.

I named this situation “3 flows antipattern”. A clean design of code separates the three flows into multiple classes (each one having exactly a single flow) using the most appropriate language features (interfaces, exceptions).

More on code design topic coming soon in a longer post.

Mar 21, 2016 - MD5 for Windows command line

Windows command line and Powershell do not have a default “md5sum” utility. There are many third party tools or PS scripts to do such a simple task. I prefer a pure Microsoft utility called FCIV: File Checksum Integrity Verifier. It can be downloaded from Microsoft site: https://support.microsoft.com/en-us/kb/841290

The usage is quite simple: fciv myfile.ext calculates the MD5 checksum of the file. fciv -sha1 myfile.ext calculates the SHA1 checksum. fciv -both myfile.ext calculates both hashes.

A note about the installation: fciv.exe is not added to the system path, so you must do it manually. Type in the command line: setx PATH "%path%;c:\fciv" (change C:\fciv with the path of your installation)

Feb 24, 2016 - Fail fast, code less

I’m embracing the “fail fast” philosophy in every project I can. What is it exactly? It is about gracefully failing when something goes wrong, and do it as soon as possible. A suggested and more in-depth article is the original “fail fast” (pdf) by Martin Fowler.

I have discovered that this approach works really well in modern Agile development, as it helps in reducing bugs and improves robustness. This sounds good but how to do it in practice? I would like to share my experience with you.

Configuration

Most applications need configuration, from a file or other sources. Often it gets complicated, long, and may be in a format prone to errors (ini files, java .properties). Environment variables can get messy too: you add one in the software and forget to set it in the CI server.

Then defaults come into play. Default number of threads for a thread pool may be a good idea. And then you are tempted to add more default values, for example for date intervals, paths, and so on. I say defaults, when used, must be explicitly stated in the logs.
The problem with defaults is when the rules to decide them are arcane or complex, or a default value does not exist (API keys are a good example). The application cannot work correctly, so it’s best to stop when a configuration property is invalid or missing.

Log with Five Ws in mind

Every configuration issue must be logged before stopping. This holds true for other issues as well. Logging is not as easy as it seems, I encountered many unhelpful lines like An error occurred. When writing a log statement it is important to remember the five Ws principle.

  • Who: stacktraces identify the source of the problem, don’t print them but always add the exception as a parameter in the log statement
  • What: add details about arguments and/or variables being processed and a meaningful description of the operation
  • Where: usually the log library provides class, method and row number
  • When: log staements grab the timestamp automatically
  • Why: discovering this is our job

A well written log line will save you lots of time debugging. Remember:
Bad: Configuration error.
Good: Configuration error in config.xml, property 'numThreads' must be an integer, value '45t' not allowed.

Global error handler

Wrap units of execution in try-catch block (or the equivalent in your language of choice). For example web requests or background threads should be wrapped. First, you are free to throw exceptions without the fear of wreaking havoc on the rest of the application. Second, you log the exception. This helps a lot when using third party libraries. Not every library correctly log unhandled exceptions, or they may get logged on another file or stream and pass unnoticed.

What’s the price?

The real price to pay for the ability to “fail fast” is not the time it takes to write log statemens or exception handling, as it may seem. The real price is gathering requirements. It’s hard to decide what to do in less trivial situations. Analyzing situations can be time consuming, client’s responses may not be immediate. Such small decisions may have a huge impact on the rest of your project. I think that having a rock-solid running software with a validated configuration will save lot of headaches and time in the long run.

I hope these suggestions will provide helpful.

About me

My online presence can be proven by the following social accounts ;-)